Re: openLilyLib website

[David Kastrup]

Urs Liska <address@hidden> writes:

> 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.)

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".