[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#32359: [PATCH] Add svg-path
From: |
Felix E. Klee |
Subject: |
bug#32359: [PATCH] Add svg-path |
Date: |
Thu, 23 Aug 2018 17:50:08 +0200 |
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