[Mplayer-cvslog] CVS: main/DOCS codecs.html,1.101,1.102 faq.html,1.118,1.119 formats.html,1.52,1.53 sound.html,1.66,1.67 video.html,1.126,1.127

[Diego Biurrun]

Gabucino writes:
 > Diego Biurrun wrote:
 > >  > -  <LI><A HREF="bugreports.html">Appendix B - How to report bugs</A>
 > >  > -    <UL>
 > >  > -      <LI><A HREF="bugreports.html#fix">B.1 How to fix bugs</A></LI>
 > > Argh, why did you remove the TOC entries???
 > Because I find it very broken idea to contain all the subsections of the
 > bugreports file, because you need to read them ALL.
 > 
 > The same went with the DGA section.

I wouldn't have taken it out, but this is probably a case where the
TOC gets too specific.  Those sections shouldn't get numbered at all
IMHO.  Have a look at one of those sections: "2.3.1.2.2.8 Known
bugs".  That's six (!) levels deep.  In bugreports.html you have
removed the second level.

I think we should follow a simple rule: If it has a number it belongs
in the TOC.

 > > I put them there for a reason
 > What was it?
 > The TOC is already very long, but we can't collapse it more, unfortunately.

Easy reference, of course, that's what a TOC is for after all.

Our TOC is long because our documentation is long, there is no helping
that.

 > > all the other appendices have a TOC, too.
 > Only:
 >  - users against developers: it contains several topics with no connection to
 >      each other, so it's just logical to provide a TOC.
 >  - skin.html: I was also thinking about collapsing its TOC, but dumped the
 >      idea, anyone would need a quick glance about its "playbar" section for
 >      example, and only for that.

And people might also want to have a quick glance at, say,
bugreports.html#crashes, like I do for example, because I still don't
know the gdb stuff by heart.

I'd like to reverse this.

While talking about TOCs: What about creating index.html that only
contains the TOC?  This way we might get rid of those strange sections
that are links in documentation.html.  But it's probably a post 0.90
redesign issue.

Diego