We are moving toward fixing the meaning of the various prefixes and that is something which should be in place for 4.0, along with documentation explaining said meanings.
GregorioRef-##.pdf (where ## is the version number) should be available on the download page for each release on an uncompressed form. I just realized that I forgot it for 3.0.2, so I'll get that up later tonight. It hasn't changed since 3.0.0. I don't know how we'd make that more visible to search engines. ✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝✝ Br. Samuel, OSB (R. Padraic Springuel) PAX ☧ ΧΡΙΣΤΟΣ > On Jun 1, 2015, at 6:47 PM, Richard Chonak <[email protected]> wrote: > > 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
