Re: Using texi2html for the documentation

[Reinhold Kainhofer]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Am Montag, 17. März 2008 schrieben Sie:
> On Sun, 16 Mar 2008 22:03:00 +0100
> > Yes, I suppose that should be possible. But if anything I'd prefer
> > "double sharp (Music Glossary)".
> > Anyway, I now found the way to remove the (lilypond-internals) etc.
> > altogether. Already fixed online
>
> Hmm, that's a pity -- I honestly thought that "(Music Glossary)
> double sharp" looked better.  I'm certainly willing to live
> without it, though.

The (lilypond-internals) is simply taken from the last argument of @ref (as 
defined in the @internalsref in macros.itexi, so that string is not supposed 
to be shown to the user. We'd need to translate it into something readable.
Also note that 

To remove the parenthesized text of the external reference, I simply hook into 
the function that formats the text for the link. It gets the default text, 
e,g, "(lilypond-internals)Voice" and the URL for the link, nothing else. 
Currently, I'm removing everything in parentheses and call the default 
function, so we might just as well insert other text into the text.

However, this adds some more clutter to the links. Look e.g. at "1.2.1.1 
Durations". Currently, there is:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Music Glossary:  breve,  longa,  note value, Duration names notes and rests. 

Notation Reference: Automatic beams, Ties, Writing rhythms, Writing rests, 
Vocal music, Ancient notation, Proportional notation. 

Snippets: Rhythms 

Internals Reference:  Dots,  DotColumn.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

With additional parentheses that would be:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Music Glossary:  (Music Glossary) breve,  (Music Glossary) longa,  (Music 
Glossary) note value  (Music Glossary) Duration names notes and rests. 

Notation Reference: (Notation Reference) Automatic beams, (Notation Reference) 
Ties, (Notation Reference) Writing rhythms, (Notation Reference) Writing 
rests, (Notation Reference) Vocal music, (Notation Reference) Ancient 
notation, (Notation Reference) Proportional notation. 

Snippets: (Snippet) Rhythms 

Internals Reference:  (Lilypond Internals) Dots,  (Lilypond Internals) 
DotColumn.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Since we split up the See also section into the different types of references 
anyway, there is no real need to duplicate that information. And putting 
everything together in one "See also" list will mix links for beginners with 
links for really advanced users.

> > Yes. However, the problem I have with the full TOC present in the
> > HTML file is the size of it.
>
> Everybody hates frames so much that it's not worth doing it that
> way?

Exactly, using frames is a big no-no for several reasons. The most compelling 
is that it prevents setting bookmarks to sub-pages.

> > In particular, I don't like the default order
> > [<][>]  [<<][UP][>>]   [Top]  [Contents]  [Index]  [ ? ]
> >
> > How about using two lines with left/center/right-aligned  links?
> > Something like:
> > [<< Musical ...]   [Top][Contents][Index][?]   [Specialist ...... >>]
> > [< Ambitus]                     [Up]                    [Special note
> > heads >]
> >
> > (And I like the idea to print them in a smaller font)
>
> Great!  That would be fantastic.  I have some quibbles about the
> middle block; IMO it would be good to have one or two items on the
> bottom line.  I have no particular idea how to divide them up at
> the moment, though.

That would be part of the screen design ;-) 
I simply split them up so that the upper line is for global navigation, while 
the lower line is for navigation by subsection.

> Can we add arbitrary text to the [?] section?  it might be good to
> insert the LM 1.6 About the documentation  text in there.  (at the
> moment I'm just asking if this is possible, not making a real
> feature request)

sure, you can have arbitrary links there...

Cheers,
Reinhold

- -- 
- ------------------------------------------------------------------
Reinhold Kainhofer, Vienna University of Technology, Austria
email: address@hidden, http://reinhold.kainhofer.com/
 * Financial and Actuarial Mathematics, TU Wien, http://www.fam.tuwien.ac.at/
 * K Desktop Environment, http://www.kde.org, KOrganizer maintainer
 * Chorvereinigung "Jung-Wien", http://www.jung-wien.at/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)

iD8DBQFH3lhUTqjEwhXvPN0RAncIAKCBQ5uEgmACwpHGu2apRhM92RRlkgCfRiWL
hDY98MaXz+Iz4G043R//Tfc=
=QIQd
-----END PGP SIGNATURE-----