Re: Issue 872 in lilypond: Changes split-page has broken images

[John Mandereau]

Le samedi 24 octobre 2009 à 17:13 +0000, address@hidden a
écrit :
> We don't *have* to discuss it as a tracker issue,

Especially when it's not necessary, as Google Code sends text emails
with horrible indentation, or rather I'm not able to fill Google Code
tracker form in a way to avoid such horrible indentation.


> Maybe those aren't good reasons... I have no objection to keeping such TODO  
> items to
> myself in the future, if that's desired.

What about the wiki for this kind of stuff?


> Anyway, for this specific issue: if changes.tely is a non-splitted manual,  
> then the
> html page from general/manual.itexi @section Changes  will overwrite the  
> non-splitted
> version of changes.itely.  I figured that the simplest way to fix this  
> would be to
> make Changes a split manual, thereby putting changes-one-page.html in the  
> main doc
> source output, and also giving us changes/index.html.

How ugly, this gives two almost identical HTML documents
changes-one-page.html and changes/index.html.


> There was also an issue with the xref produced by @rchanges{Top,blah}  
> inside general,
> that has to do with the broken html refs that I'm avoiding with that  
> disgusting find
> | xargs sed trick.

One purpose of postprocess_html is avoiding messing with make and shell
to do such tricks.


> In general (umm, I mean, "as a summary", not anything to do with  
> general.texi), I'd
> like to avoid manual-specific hacks; I like the idea of only having two  
> types of
> manuals: general.texi, which goes in the top output dir, and all the other  
> manuals,
> which are all treated the same.

There are two distinct documentation targets: online (lilypond.org) and
offline (downloadable docball).

As for the offline target, I don't understand why you want to make
General go at the top output dir: why should the directory structure
match the hierarchy between HTML Info manuals?  The only grounds I can
see for doing so would be
- navigating directories/typing URL by hand,
- reading the URL to see where you are because the docs structure is not
obvious from the HTML pages themselves.

I hope we put enough effort into the usability of our docs and new web
site so these grounds are not valid.

As for the online docs, we want
- the website in lilypond.org/web (IIRC you suggested lilypond.org,
which changes nothing to the issue)
- the docs in lilypond.org/doc/vX.Y/

Moving HTML output of General one directory up suits none of the two
targets, so it should be abandoned.  However, we should generate each
output of General twice, removing for the offline target the download
page and other pages that make sense only for the online web site; I'm
willing to take over this, but not for the to-be-dead build system.


> Long-term, I think it would be nice to have the older Changes in the same  
> document,
> but I haven't thought through all the issues involved in doing this.    
> (namely, what
> happens if the syntax changes from 1.4 to 1.8, then again from 1.8 to 2.13  
> -- how do
> we generate the picture for the changes-1.8 page?)

Let's not have a headache for this :-)


> Now that I think about it some more, I'm leaning towards abandoning the  
> idea entirely.

I second this.  It's (and it should be with the new web site) easy to
see changes for each new stable branch from the page Documentation from
the web site.

Best,
John

signature.asc
Description: Ceci est une partie de message numériquement signée