Re: [Denemo-devel] Denemo Manual

[Richard Shann]

Stuart - I've moved this back on to the mailing list, as others are more
knowledgeable about some of the topics than I. (hope you don't mind!)

> The new (1.2.4) manual is much better than the old one! [...] need to
> solve the issue with the graphics - the toolbar and playback control
> sections aren't much use without them. I see that (with the exception
> of the note.png icon that goes with the <note> sections) the images
> are all referred to in the XML file. I guess the images directory is
> not being included with the output for some reason.

I've put a note in the manual to warn about that - the fix is not
trivial as the html is being extracted from the git repository on the
fly, so there is no images directory present, nor denemo.css

> I also don't see them in my local version (which has the older 0.9.4
> manual version).

This is a bug in the install for windows, they are present for GNU/Linux
(and I would guess Mac) users. I've raised a bug report about this -
thank you!
On all machines the denemo.css is not being installed which I have also
raised a bug for.

> There are also a some areas that need clarification (such as how to
> use the Score Layout dialog). The manual mentions things that are
> possible with this dialog, but lacks details about how to accomplish
> these things.  If you click the Customize button, for example, you get
> a dialog asking if you want to "Replace Standard Layout?" (and the
> warning that follows if you choose yes is pretty cryptic). A little
> experimentation gave me a better feel for how it works. I'd be happy
> to write some additions to the manual, help with editing existing
> sections, additional formatting, etc. Just let me know what would be
> most helpful.

The reason this is not better documented is that I never got happy with
this interface and have hopes that I might re-do it in a different way.
It is usable but too complicated.

[...]
> Are you editing the denemomanual.xml file by hand or are you using an
> xml editor?
I'm just using a text editor, though it does seem to have some xml
awareness.
> You're using docbook to generate the html version of the manual. Are
> you making the manual available in other formats (i.e. print, PDF,
> etc.) as well?

This question had me looking around for evidence that other formats have
ever been generated ... there's an astonishing amount of crud in the
docs directory, but no sign that any further use has been made of the
docbook format.

>  If so, then there's a good case for sticking with the current
> process. If not (if the manual is only being distributed in html
> format), then there are much easier and more robust editors out there.
> Near as I can tell, GNU recommends (but does not require) that manuals
> be available in Textinfo format, which can be converted into a variety
> of different documentation formats.

I just tried getting the docbook2x program for generating Texinfo format
and it failed to do the job. I suspect bit rot as the last version is
eight years old. I have been plagued over the years with docbook
changing, requiring some asking around at each upgrade of my Debian o/s.
But I wouldn't want us to rush from frying pan to fire. I recall
Jeremiah expressing an interest in moving on to something better for the
docs some years ago...

Richard


>