Urs Liska <li...@openlilylib.org> writes: > Hi David, > > Am Sonntag, den 23.02.2020, 22:12 +0100 schrieb David Kastrup: >> Urs Liska <li...@openlilylib.org> writes: >> >> > Hi all, >> > >> > as a starting point for a - hopefully - comprehensive documentation >> > effort I have finally updated https://openlilylib.org with a >> > completely >> > new website, which I'd like to have some feedback about and >> > contributions for. >> > >> > There are several parts to that effort, most of which are >> > essentially >> > not started yet. >> > >> > * A general introduction website. This is basically complete and >> > should finally give a proper introduction about what OLL "is" >> > and >> > how it can be made to work >> > * Independent sub-sites for each OLL package. These have not been >> > written at all, only the links to empty starting pages work >> > without >> > 404 errors. >> > * I've settled with MkDocs (https://www.mkdocs.org), which seems >> > to >> > provide what I need, especially a suitable way to hook into and >> > extend to our needs. >> > * Each sub-site is maintained in a separate Git repository and >> > included as a Git submodule, so it should be straightforward to >> > manage independent authoring of the documentation by the >> > respective >> > package maintainers. >> > * There's a link to a contributor's guide, which is also >> > essentially >> > empty, except for an entry page. >> > >> > What I have so far is an infrastructure for textual, Markdown- >> > authored >> > manuals, although I have already created a plugin for LilyPond >> > syntax >> > highlighting using python-ly ( >> > https://github.com/uliska/markdown-lilypond/). >> > >> > What I really *want* to have but have no idea so far how to achieve >> > is >> > additional code/API documentation retrieved from the actual source >> > files. There should be a tool to retrieve that from comments (or >> > actual >> > signatures?), resulting in either HTML or Markdown documentation >> > that >> > can be automatically integrated in the "manual-style" >> > documentation. >> > > I must admit I don't fully understand what your comments are actually > targeted at. > >> With regard to the LilyPond-book/Texinfo route, it might be worth >> considering that Asciidoc (which Git documentation is written in) can >> be >> converted via the route (grabbed lines from the git Documentation >> Makefile): >> >> user-manual.texi: user-manual.xml >> $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ >> $(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >> >$@++ && \ >> $(PERL_PATH) fix-texi.perl <$@++ >$@+ && \ >> rm $@++ && \ >> mv $@+ $@ >> >> user-manual.xml: user-manual.txt user-manual.conf >> $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ >> $(TXT_TO_XML) -d book -o $@+ $< && \ >> mv $@+ $@ >> >> ASCIIDOC = asciidoc >> ASCIIDOC_EXTRA = >> ASCIIDOC_HTML = xhtml11 >> ASCIIDOC_DOCBOOK = docbook >> ASCIIDOC_CONF = -f asciidoc.conf >> ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \ >> -agit_version=$(GIT_VERSION) >> TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) >> TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK) >> >> DOCBOOK2X_TEXI = docbook2x-texi >> >> So that's a bunch of stuff that can convert via Docbook XML to >> Texinfo. >> And it's likely that some Wiki-acceptable format convertable to >> Docbook >> XML exists. > > I've had a look at the Asciidoc homepage, and it looks like a tool I > might like. > > But at this point we are talking about HTML targets (possibly PDF too), > Markdown files and documentation generated from LilyPond/Scheme files. > Nothing about DocBook, texidoc etc. > > What are you actually intending to convey with these Makefile excerpts? > That I should consider AsciiDoc as a possible platform for the > documentation? What would be in there that makes it a (better and) > suitable tool for the task? > (This is not meant as an objection [somewhat hard to express], rather a > request for clarification. I need more a more concrete idea what you > want me to consider.)
Basically this boils down to pointing out that Texinfo, which has some prominence in the LilyPond core, has conversion paths via docbook2x-texi from formats that are more akin to what one would use automated documentation extraction on. That's all. I have not enough clue about openLilyLib to figure out whether that information might be useful for you. I just threw that out and it would seem like I made it sound like more (or something different) than it actually is. Just some keyword-triggered info that may or may not be interesting for whatever this conversation I barreled in was about. Sorry if it's just nonsense and occupied too much of your time trying to make sense of. David -- David Kastrup My replies have a tendency to cause friction. To help mitigating damage, feel free to forward problematic posts to me adding a subject like "timeout 1d" (for a suggested timeout of 1 day) or "offensive".
