Hi David, Am Sonntag, den 23.02.2020, 22:12 +0100 schrieb David Kastrup: > Urs Liska <[email protected]> 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.) Urs >
