[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: openLilyLib website
From: |
Urs Liska |
Subject: |
Re: openLilyLib website |
Date: |
Mon, 24 Feb 2020 00:58:07 +0100 |
User-agent: |
Evolution 3.34.1-3 |
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
>