Regarding the topic of GregorioTeX macro documentation,
On 06/01/2015 02:59 PM, Br. Samuel Springuel wrote:
Élie and I had a discussion about this at some point, and bounced
around the idea of focusing the website on introductory information
(installation, basic usage tutorial, etc.), leaving a full explanation
of all the different functions for the detailed documentation
elsewhere (this is turning out to be GregorioRef, sort of by default
since we have it and are slowly adding to it). Basically, we didn't
want to have to maintain too many things. The more that needs to be
maintained, the less likely it is to get updated.
There was some talk
(https://github.com/gregorio-project/gregorio/issues/103) about
adopting some other form of documentation to make it possible to
automatically extract the documentation from the source and keep a
website upto date that way, but so far we haven't actually moved on that.
I'm glad to see that this much work has been done on documenting the
macros and variables of Gregorio.
May I suggest adding a preliminary section to the document, on naming
conventions, if this isn't already on the Issues list? Some of the
macros listed in the document start with the prefix "gre", some have
"gre@", a few have "Gre", while some have no prefix. These prefixes
should be explained, if they have a meaning: that is, if they are being
used to distinguish commands from variables, or "public" from "private"
interfaces. Any naming inconsistencies should eventually be reformed
(an objective for Gregorio v4, I suppose).
GregorioRef.pdf is not accessible via web searches, inasmuch as the PDF
file is only provided in release distributions. Tucked away inside a
compressed tar file, it is not found by search-engine robots, and the
file does not appear in Google search results. (For example:
http://tinyurl.com/q2ycunw ) GregorioRef.tex is found as a search
result, but users cannot build the PDF from it, if their TeXLive is 2013
or earlier, unless they install the Inconsolata font. So it seems that
GregorioRef.pdf is somewhat hidden from view.
As a matter of opinion, I recognize that documenting TeX packages in the
form of PDF documents is the Received Tradition of TeX, but I wonder if
relying on that format exclusively is still "best practice".
Thanks for the documenting work done so far!
--Richard
_______________________________________________
Gregorio-devel mailing list
[email protected]
https://mail.gna.org/listinfo/gregorio-devel
