Re: openLilyLib website

[Urs Liska]

Hi David,

Am Sonntag, den 23.02.2020, 22:12 +0100 schrieb David Kastrup:
> Urs Liska <address@hidden> 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

>