bug#32359: [PATCH] Add svg-path

[Felix E. Klee]

Hi Eli,

thanks for the feedback!

On 8/3/18, Eli Zaretskii <eliz@gnu.org> wrote:
> We don't maintain a ChangeLog file; the above should be the commit
> log message.

Well, the Emacs info page on committing patches states: “Write the
change log entries for your changes. […]”

Furthermore, it links to a page explaining `ChangeLog' files in
particular. Is that documentation outdated?

`ChangeLog.3' contains entries for previous additions to `svg.el', the
latest one as recent as September 2017.

Anyhow, if you want a commit log instead of a `ChangeLog' entry, how
should I submit the commit?

>> +@defun svg-path svg commands &rest args
>> +Add the outline of a shape to @var{svg}. The @var{commands} follow the
>> +Scalable Vector Graphics standard. This function can be used to create
>> +arcs.
>
> This is too cryptic for the manual,

It’s basically in line with the description for the other `svg' functions.

> and the example doesn't help enough.

For the intended audience, i.e. those knowing how to author SVG
documents, it should be clear. What I could do is add aliases for the
path commands:

  * `moveto-relative' → `m'

  * `moveto-absolute' → `M'

  * etc.

The example would then turn into:

    (svg-path svg '((moveto-absolute 100 300)
                    (arc-absolute 300 300 0 0 0 300 100)
                    (closepath-absolute))
              :stroke-color "blue" :fill-color "yellow")

Still users would need to know the command parameters which are
detailed in every comprehensive documentation about SVG.

> We should at least explain what "arcs" means in this context,

“arcs” in the context of SVG, i.e. vector graphics refers to curved
paths:

https://www.merriam-webster.com/dictionary/arc

> and in general what is this function about; also what kind of object
> is SCG.

Quote from the documentation in the elisp info page for `svg.el': “SVG
(Scalable Vector Graphics) is an XML format for specifying images.”

> In general, GNU Coding Standards frown upon using "path" for
> anything that is not PATH-style directory lists, so maybe use a
> different name or explain what kind of "path" is being referenced
> here.

Renaming `path' would be super confusing to those familiar with vector
graphics. If `path' needs to be avoided, then I’d rather not add
`svg-path'.

Instead one could add a more general:

    svg-node (parent tag &rest args)

This function is needed anyhow. It would be for inserting custom SVG
nodes, i.e. nodes beyond those currently available in the `svg'
package.

BTW I got in contact with Lars, the original author of `svg.el', and
he’s OK with the changes I proposed, including some additional
functions.

/ Felix