RE: Using texi2html for the documentation

[Trevor Daniels]

Reinhold

This is looking really promising!  I like the navigation
bar at the left.  It is so much easier to move between
sections.

A minor problem with boxes.  Round a warning they seem a
little overdone (I known they are not all from texi2html)
- see
http://kainhofer.com/~lilypond/texi2html-out/Ties.html#Ties

and the box round a short example looks strange - see
second example in
http://kainhofer.com/~lilypond/texi2html-out/Rests.html#Rest
s

I wonder if the boxes are worth retaining?

I like the links named as they are.  The external ones
break,
but I guess that is expected at this stage.

Otherwise looks pretty good!

Trevor D

> -----Original Message-----
> From: address@hidden
> [mailto:lilypond-devel-bounces+t.daniels=treda.co.
> address@hidden Behalf
> Of Reinhold Kainhofer
> Sent: 20 March 2008 18:29
> To: Undisclosed.Recipients:
> Cc: LilyPond Development
> Subject: Re: Using texi2html for the documentation
>
>
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Here is an update about the current situation
> with texi2html for the docs
> building. The current version is at:
>
>
> Am Sonntag, 16. März 2008 schrieb Graham Percival:
> > Lists are destroyed.  Look at:
> >
> http://kainhofer.com/~lilypond/texi2html-out-tradi
> tional/Writing-pitches.ht
> >ml#Relative-octave-entry
>
> Fixed by Patrice Dumas (who is simply amazing:
> Ask him about a problem and an
> hour later you'll either have an explanation how
> to do it, or if it's a bug,
> he will have fixed it already).
>
> > > (Don't worry about the long toc on the left,
> I simply haven't yet
> > > found a way to show only two levels plus the
> full path to the current
> > > page).
> >
> > I'm not certain we only want two levels... the
> ideal would be if
> > users could click to expand/contract each tree.
>  Perhaps two
> > levels would be good by default, but I'd like
> it if people could
> > expand them to see three or four levels.
>
> I've implemented it now so that two levels are
> shown by default, plus the full
> path to the current page (with their siblings, so
> it behaves just like in a
> file browser). Example:
> http://kainhofer.com/~lilypond/texi2html-out/Perce
> nt-repeats.html
>
> > This would be also very cool if the node
> currently displayed was
> > highlighted in the TOC.
>
> Also, the current page (and its ancestors) are
> printed in bold and italic
> (style is completely up to the design, so we can
> change that easily in
> the .css file) in the toc on the left.
>
> > > Some people might wonder about the
> "(music-glossary)double sharp"
> > > links, but I actually prefer them this way --
> it makes it clear
> > > where it's going.  One tiny nitpick: could we
> have a space between
> > > the ) and the next character?
> > > - if this is difficult, forget about it;
> there's much more
> > >   important things to fuss about.
> >
> > After quickly looking at texi2html docs, it
> should be possible to get
> > any desired output by redefining the output
> function, e.g.
> > "Music Glossary, double sharp", which is much
> prettier than
> > "(music-glossary)double sharp".  If we keep
> "See also" sections as they
> > are, i.e. with references grouped by external
> manual name, we should
> > even have two different external ref commands
> for HTML ouptut, one with
> > the name of the manual, and one without it.
>
> I put this up for discussion: Currently we have
> the links already split by
> external refs (i.e. one line for Music Glossary
> links, one or IR links, one
> for Snippet links). As long as it stays like
> this, I don't think we should
> show the target external manual name again, since
> it is already printed at
> the begining of the line...
>
> > - navigating the pages with the keyboard (Alt-U
> for up, Alt-P for
> > previous, Alt-1 for first menu entry and so
> on); this should be easy to
> > add this in texi2html, the HTML code looks like
>
> Patrice will take a look at implementing access
> keys in the next few days.
>
>
> > - the navigation bar at top and bottom of each
> page is very handy, but
> > it misses section titles; it'd be very cool if
> texi2html could print the
> > titles too,
>
> Implemented.
>
>
> > I'd like to improve the process of translated
> docs HTML output.
> > The problem is, node names and section titles
> should of course be
> > translated in the ouptut, but we want HTML page
> names and anchors use
> > the node names in English even in translated
> docs, for the sake of easy
> > per-page switching and working cross-references
> even if the destination
> > page is not translated (thus redirecting to the
> corrseponding page in
> > English).
>
> Currently that's not possible, because for
> determining the file name, we have
> only the section name, number and ID available,
> but not the contents of the
> section. There is also no chance to set some
> property in a macro, because
> that will only be expanded later on. However,
> Patrice seems to have an idea
> to move macro evaluation to an earlier place and
> make this possible.
>
> Looking at the texi file:
> Do we really still need the @node before each
> section/chapter with texi2html,
> since splitting is then based on sections anyway?
> Currently, this causes two
> identical <a name="section_id"> anchors into the page...
>
>
> > At the moment, I have no real opinion on all
> the CSS stuff,
> > except to agree with you that it's somewhat
> subjective.  However, I'm
> > sure we have a few CSS geeks on the -user, not
> to mention Valentin...
>
> Actually, we don't need any CSS geeks (I know CSS
> well enough to implement
> anything we might need, even up to automatically
> expanding sub-menus on
> mouse-over, implemented entierly in CSS, see e.g.
> http://www.jung-wien.at/designtest.php, which I
> find annoying..). What we
> need is some good graphical designer, who makes a
> screen design (e.g. as
> image, PDF, PhotoShop, etc.) for all the design
> elements that the docs (and
> the main lilypond.org page) contain.
>
> > I'm just glad to see that these opportunities
> are offered now; I think
> > a community needs to be motivated by visible
> (superficial) spectacular
> > initiatives, more than *really* important (but
> invisible to them)
> > program code etc. In other words, IMO you have
> to make it sexy to
> > motivate people.
>
> That's exactly the reason, why I'm pointing at
> improving the appearance of the
> web page ;-) Our documentation is really great,
> the application itself, too,
> only the start page looks a bit bare compared to
> what gems are hidden behind
> it...
>
>
>
> About translations: texi2html has full
> translation support, I've sent Patrice
> the updated German strings, he wrote the French
> ones, so we might only miss
> some Spanish strings...  I have not yet looked at
> adding the language to the
> file name (i.e. use .de.html as extension for the
> German docs).
> About the automatic language selection: I think
> inside the manual, we should
> generate links to the full file names (i.e.
> pointing to Rhythms.html,
> Rhythms.de.html, Rhythms.fr.html) and not leave
> out the extension (i.e.
> pointing to Rhythms). My reason is that if you
> leave out the extension,
> automatic language selection will be applied to
> each and every page. Since my
> Browser defaults to German, I will always get the
> German docs. Now, if I want
> to see the English one, I click on the
> alternative translation and get the
> English files. However, all links on that page
> are again without the
> extension, so clicking on them, I'll again end up
> with the German version...
> So, for me this automatic language selection is
> really annoying!
>
> For the index page, I think it's a good idea to
> have automatic language
> selection, but from the on, all links should
> point to the files for the same
> language as the current page.
>
> BTW, is the automatic language selection (i.e.
> creating links without .html
> extension and adding the "Alternative languages"
> link on the bottom)
> implemented directly in makeinfo, or does
> lilypond's build system some more
> magic to get this?
>
>
>
>
> Further issues that are still open (for most of
> them, I have already sent a
> mail to Patrice, and he is aware of them and
> might even implement a fix
> shortly):
>
> - -) "Short" TOC for the start/contents/about
> page. Currently, I can only put
> the full TOC there, while I want to show only the
> first two levels (like on
> any other page)
>
> - -) For pages with multiple subsections shown on
> the same file, I want the
> navigation panel between the subsections to show
> only the [<..] [Up...]
> [...>] buttons, but not the chapter navigation
> ones (i.e. [<<] [Contents]
> [Top]...[...>>]).
>
>
> 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)
>
> iD8DBQFH4qztTqjEwhXvPN0RAiULAKCkvjY+nhPoahmGakQ9sG
> 6xfNhRlQCgiXNy
> NrhDuXOpLMgHAA+uuqwI6y0=
> =KUWR
> -----END PGP SIGNATURE-----
>
>
> _______________________________________________
> lilypond-devel mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/lilypond-devel
>