Scribus scripting functions documentation in source code

Previous topic - Next topic

Darkoni

Hi!

When I looked at and analyzed the source code, I noticed that a dozen Scribus scripting functions had poorly formatted descriptions.

If you would be willing to correct them, I am attaching a list of errors and a list of my suggestions on how to correct them.

* currentPage() -> integer
* currentPage() -> integer
* currentPage() -> integer Returns the number of the current working page based on the section of the document.
* getImageColorSpace(["name"]) -> integer Returns the color space for the image loaded in image frame "name" as one of following integer constants: CSPACE_RGB (0), CSPACE_CMYK (1), CSPACE_GRAY (2), CSPACE_DUOTONE (3) or CSPACE_MONOCHROME (4). Returns CSPACE_UNDEFINED (-1) if no image is loaded in the frame. If "name" is not given the currently selected item is used.
* getLineCap(["name"]) -> integer (see constants)
* getLineJoin(["name"]) -> integer (see constants)
* getLineStyle(["name"]) -> integer (see constants)
* getObjectAttributes(["name"]) -> list Returns a list containing all attributes of object "name".
* getUnit() -> integer (Scribus unit constant)
* Obsolete function. Don't use it.
* setitemname(newName, ["name"])
* setitemname(newName, ["name"])
* Scribus internal.
* Scribus internal.

### 01. currentPage()

File: scribus/plugins/scriptplugin/scriptplugin.cpp

Set function name to currentPageNumberForSection() and remove spaces in front of lines

/*! docstring */
PyDoc_STRVAR(scribus_currentpagenumberforsection__doc__,
QT_TR_NOOP("currentPageNumberForSection() -> integer\n\
\n\
Returns the number of the current working page based on the section of the document.\n\
\n\
"));
/*! get actual page */
PyObject *scribus_currentpagenumberforsection(PyObject * /*self*/);

I see that currentPage and currentPageNumber calls the scribus_currentpage function.

But, when people are creating documentation from Scribus source, then they will get [/b]currentPage[/b] twice.

Like here:

https://impagina.org/scribus-scripter-api/page/

That can be fixed by adding

/*! docstring */
PyDoc_STRVAR(scribus_currentpagenumber__doc__,
QT_TR_NOOP("currentPageNumber() -> integer\n\
\n\
Returns the number of the current working page. Page numbers are counted from 1\n\
upwards, no matter what the displayed first page number of your document is.\n\
"));
/*! get actual page */
PyObject *scribus_currentpage(PyObject * /*self*/);

And changing line

{const_cast<char*>("currentPageNumber"), (PyCFunction)scribus_currentpage, METH_NOARGS, tr(scribus_currentpagenumber__doc__)},

### 02. getImageColorSpace(["name"]) -> integer

File: scribus/plugins/scriptplugin/cmdgetprop.h

/*! docstring */
PyDoc_STRVAR(scribus_getimagecolorspace__doc__,
QT_TR_NOOP("getImageColorSpace([\"name\"]) -> integer\n\
\n\
Returns the color space for the image loaded in image frame \"name\" as one of following integer constants:\n\
CSPACE_RGB (0)\n\
CSPACE_CMYK (1)\n\
CSPACE_GRAY (2)\n\
CSPACE_DUOTONE (3)\n\
CSPACE_MONOCHROME (4)\n\
CSPACE_UNDEFINED (-1) if no image is loaded in the frame.\n\
If \"name\" is not given the currently selected item is used.\n\
"));
PyObject *scribus_getimagecolorspace(PyObject * /*self*/, PyObject* args);

### 03. getLineCap(["name"]) -> integer

File: scribus/plugins/scriptplugin/cmdgetprop.h

/*! docstring */
PyDoc_STRVAR(scribus_getlinecap__doc__,
QT_TR_NOOP("getLineCap([\"name\"]) -> integer\n\
\n\
Returns the line cap style of the object \"name\".\n\
If \"name\" is not given the currently selected item is used.\n\
The cap types are:\n\
CAP_FLAT, CAP_ROUND, CAP_SQUARE\n\
"));
/*! Returns cap type of the line */
PyObject *scribus_getlinecap(PyObject * /*self*/, PyObject* args);

### 04. getLineJoin(["name"]) -> integer

File: scribus/plugins/scriptplugin/cmdgetprop.h

/*! docstring */
PyDoc_STRVAR(scribus_getlinejoin__doc__,
QT_TR_NOOP("getLineJoin([\"name\"]) -> integer\n\
\n\
Returns the line join style of the object \"name\".\n\
If \"name\" is not given the currently selected item is used.\n\
The join types are:\n\
JOIN_BEVEL, JOIN_MITTER, JOIN_ROUND\n\
"));
/*! Returns join type of the line */
PyObject *scribus_getlinejoin(PyObject * /*self*/, PyObject* args);

### 05. getLineStyle(["name"]) -> integer (see constants)

File: scribus/plugins/scriptplugin/cmdgetprop.h

/*! docstring */
PyDoc_STRVAR(scribus_getlinestyle__doc__,
QT_TR_NOOP("getLineStyle([\"name\"]) -> integer\n\
\n\
Returns the line style of the object \"name\".\n\
If \"name\" is not given the currently selected item is used.\n\
Line style constants are:\n\
LINE_DASH, LINE_DASHDOT, LINE_DASHDOTDOT, LINE_DOT, LINE_SOLID\n\
"));
/*! Returns style type of the line */
PyObject *scribus_getlinestyle(PyObject * /*self*/, PyObject* args);

### 06. getObjectAttributes(["name"]) -> list

File: scribus/plugins/scriptplugin/cmdgetprop.h

/*! docstring */
PyDoc_STRVAR(scribus_getobjectattributes__doc__,
QT_TR_NOOP("getObjectAttributes([\"name\"]) -> list\n\
\n\
Returns a list containing all attributes of object \"name\".\n\
"));
PyObject *scribus_getobjectattributes(PyObject * /*self*/, PyObject* args);

### 07. getUnit() -> integer

File: scribus/plugins/scriptplugin/cmddoc.h

/*! docstring */
PyDoc_STRVAR(scribus_getunit__doc__,
QT_TR_NOOP("getUnit() -> integer\n\
\n\
Returns the measurement units of the document.\n\
The returned value will be one of the UNIT_* constants:\n\
UNIT_INCHES, UNIT_MILLIMETERS, UNIT_PICAS, UNIT_POINTS.\n\
"));
/** Returns actual unit scale. */
PyObject *scribus_getunit(PyObject * /*self*/);

### 08. Obsolete function. Don't use it.

File: scribus/plugins/scriptplugin/scriptplugin.cpp

Please, comment line as it is obsolete.

// {const_cast<char*>("pageDimension"), (PyCFunction)scribus_getpagesize, METH_NOARGS, "Obsolete function. Don't use it."},

### 09. setitemname

The better name for function is setItemName

https://www.techtarget.com/whatis/definition/CamelCase

File: scribus/plugins/scriptplugin/cmdsetprop.h

/*! docstring */
PyDoc_STRVAR(scribus_setitemname__doc__,
QT_TR_NOOP("setItemName(newName, [\"name\"])\n\
\n\
Sets the name of object \"name\" to newName and returns the name applied.\n\
If \"name\" is not given the currently selected item is used.\n\
\n\
May raise NotFoundError if the object doesn't exist.\n\
"));
/*! Set newname */
PyObject *scribus_setitemname(PyObject * /*self*/, PyObject* args);

Comment line to remove call to function [/b]setNewName[/b]

File: scribus/plugins/scriptplugin/scriptplugin.cpp
// {const_cast<char*>("setNewName"), scribus_setitemname, METH_VARARGS, tr(scribus_setitemname__doc__)}, // Deprecated, was in fact never documented

### 10. Scribus internal.

File: scribus/plugins/scriptplugin/scriptplugin.cpp

Please, change

// {const_cast<char*>("retval"), (PyCFunction)scribus_retval, METH_VARARGS, const_cast<char*>("Scribus internal.")},
// {const_cast<char*>("getval"), (PyCFunction)scribus_getval, METH_NOARGS, const_cast<char*>("Scribus internal.")},
{const_cast<char*>("retval"), (PyCFunction)scribus_retval, METH_VARARGS, tr(scribus_retval__doc__)},
{const_cast<char*>("getval"), (PyCFunction)scribus_getval, METH_NOARGS,  tr(scribus_getval__doc__)},

And add to file scribus/plugins/scriptplugin/cmdsetprop.h

/*! docstring */
PyDoc_STRVAR(scribus_retval__doc__,
QT_TR_NOOP("retval()\n\
\n\
Scribus internal.\n\
\n\
"));

and

/*! docstring */
PyDoc_STRVAR(scribus_getval__doc__,
QT_TR_NOOP("getval()\n\
\n\
Scribus internal.\n\
\n\
"));

Thanks!

Darko Nikolić

Darkoni

And there is another feature in Scribus code:

### 11. LINE_< style >

File: scribus/plugins/scriptplugin/cmdsetprop.h

/*! docstring */
PyDoc_STRVAR(scribus_setlinestyle__doc__,
QT_TR_NOOP("setLineStyle(style, [\"name\"])\n\
\n\
Sets the line style of the object \"name\" to the style \"style\". If \"name\"\n\
is not given the currently selected item is used.\n\
Argument for this function is number - value from 1 to 37\n\
There are few predefined constants for \"style\" - LINE_< style >.\n\
In Property Palette this feature is selected in box named 'Type of line'\n\
"));
/*! Set line end */
PyObject *scribus_setlinestyle(PyObject * /*self*/, PyObject* args);

Why is this important?

There is a nice site Scribus Scripter API

https://impagina.org/scribus-scripter-api/

"This API documentation has been generated from Scribus 1.7.0.svn (2023-11-18)."

And on one of the pages there is missing content.

https://impagina.org/scribus-scripter-api/other-style/

Missing documentation for setTableStyle and also page footer is missing.

All because of HTML tag style in Scribus code.

All becouse of text LINE_< style > in code.

Could Scribus dev team fix this minor thing?

Thanks!

Darko Nikolić

a.l.e

fixing the docstrings is for sure a good thing. but i find it hard to follow the all the changes you're suggesting.

since you're already using gitlab, would you mind creating a new branch with the changes, create a merge request and adding the link in here?

then we can start a review on gitlab with inline comments attached to the specific lines of code.

sadly it's not (yet) possible to accept merge requests, but if you're as lazy as i am, you can add a .diff to the url and create a diff that you can download and use for uploading to the scribus bug tracker : - )

a.l.e

concerning the < style > ... i guess that i will have to tweak my script to convert it to &lt; style &gt; .

theoretically, < and > can be the start and html tags and should be escaped... but since they mostly work i normally don't do it.


MrB

As Ale points out, this is a problem with the website conversion code, should should set to &lt; or &gt;, not Scribus code.

Darkoni

MrB

You are right. I will format special chars to HTML tags: &lt; &gt; &amp;

Thanks for pointing out.

I find there are other 'strings', namely:

PAPER_<paper_type>
UNIT_<type>
FILL_<type>
CAP_<type>
JOIN_<type>
LINE_<style>
<selection>
0 <= state <= 3
<i></i>

Note that only <style> causes trouble.

I will leave point 11. as it is.

But, what about the other points on this forum thread?

Regards

MrB

I'm happy to review all of these changes, potentially all for 1.7.0 codebase, and some, maybe all for 1.6.1. We're waiting on one last thing to release 1.6.0 which is the French UI translation. Once that's done by Jean, we'll release it. After that, we can look at all of this stuff. Thank you for reviewing those scripter functions.

Darkoni


I have made a merge request:

https://gitlab.com/scribus/scribus/-/merge_requests/46

Looking forward to discuss and see the changes.

Best regards,
Darko Nikolić

a.l.e

voilà, i've submitted my review!

see you there : - )