198901 - Mozilla release notes should be written in DocBook

Status: VERIFIED WONTFIX

(www.mozilla.org :: General, enhancement)

Description

[Roland Mainz]

RFE: Mozilla release notes should be written in DocBook. This would allow a more
flexible handling of various issues like:
- generate per-build release notes which are specific for that OS/platform, even
vendor-specific changes won't be a problem anymore
- the release notes could be split over many small files instead of having one
horrible large piece of HTML code
- clean seperation from content and style
- docbook-to-html convertion can handle the use of multiple alternative styles
("normal", "compact", "full", "printing", etc.)
- docbook allowed to generate an index/overview automagically
- no more dead links
- no more invalid HTML code
etc. etc.

Comment 1

[rudman]

-->asa.

Comment 2

[Daniel Wang]

suggest wonfix
from what I read in n.p.m.documentation newsgroup, there's strong
resistance among d11n contribuotrs to use DocBook
-> mozilla.org (d11n:user is for Help conents)

Comment 3

[rudman]

Agreed that this should be Wontfix. 

The subject of DocBook has come up in the past. DocBook presents too many
hurdles to contributors. It would be overkill to use for the release notes,
despite the attractive reasons for using DocBook as provided by the bug
reporter. DocBook would be more meaningful for producing a single-sourced,
multiple format/output, large suite of documentation. And even there, the high
barrier to entry for contributors (lack of tools, new technology to learn) is
largely prohibitive.

Comment 4

[Roland Mainz]

rudman wrote:
> Agreed that this should be Wontfix.

How would you fix the problems I listed in my first comment? The current release
notes are a horrible mess from both content (much stuff is incomplete and
outdated) and used HTML code. And the source file has become _huge_, IMHO
splitting it into multiple parts won't harm... but... HTML does not support
splitting of one document into smaller pieces and then display them as one
piece.

> The subject of DocBook has come up in the past. DocBook presents too many
> hurdles to contributors. It would be overkill to use for the release notes,
> despite the attractive reasons for using DocBook as provided by the bug
> reporter. DocBook would be more meaningful for producing a single-sourced,
> multiple format/output, large suite of documentation. And even there, the high
> barrier to entry for contributors (lack of tools, new technology to learn) is
> largely prohibitive.

Er... why are other projects like Gnome, KDE, Xfree86, Linux etc. and companies
like IBM, Sun etc. then able to use DocBook? Obviously their
contributors/engineers have no problems with using DocBook (de-facto industry
standard for (computer/engineering) documentation), even for stuff like _small_
Unix manual pages. At it is much better than using the homegrown junk of HTML
code we're currently having in the release notes.
And the "switch over" to DocBook could be "done" incrementally, e.g. we could
use a "HTML-like" subset for the first version and then - step-by-step - refine
that work.

Comment 5

[Dave Miller [:justdave]]

I have neither an opinion on this (I'm not a Mozilla developer) nor any
authority over a decision here.  But just for the record, we use Docbook for the
documentation for Bugzilla, and it works well for us.

We have a relatively short, sweet tutorial on how to set it up in the root of
our docs directory. 
http://lxr.mozilla.org/mozilla/source/webtools/bugzilla/docs/README.docs

The main hurdle is getting the software installed.  Once it's up and running
editing the files isn't much worse than HTML.

But the big thing is you don't even need the software to be able to edit the
sgml/xml files, you only need the software to compile the final product.  We
take lots of sgml patches from contributors that need tweeking to get them to
compile. :)  That's the job for our docs guy to compile it, the contributors
basically provide content.

Comment 6

[Daniel Wang]

can't set this to future. -> nobody . We have other higher priority bugs

Comment 7

[Asa Dotzler [:asa]]

even better, ->wontfix. As long as I'm involved in the release notes, they're
not going to docbook. sorry.

Comment 8

[Daniel Wang]

gladly verifying