Mozilla release notes should be written in DocBook

VERIFIED WONTFIX

Status

--
enhancement
VERIFIED WONTFIX
16 years ago
6 years ago

People

(Reporter: roland.mainz, Unassigned)

Tracking

Firefox Tracking Flags

(Not tracked)

Details

(Reporter)

Description

16 years ago
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

16 years ago
-->asa.
Assignee: rudman → asa

Comment 2

16 years ago
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)
Assignee: asa → endico
Component: User → webmaster@mozilla.org
Product: Documentation → mozilla.org
QA Contact: rudman → imajes
Summary: RFE: Mozilla release notes should be written in DocBook → Mozilla release notes should be written in DocBook
Version: unspecified → other

Comment 3

16 years ago
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.
(Reporter)

Comment 4

16 years ago
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.
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.

Updated

16 years ago
Blocks: 186272

Comment 6

15 years ago
can't set this to future. -> nobody . We have other higher priority bugs
Assignee: endico → nobody
QA Contact: imajes → nobody

Updated

15 years ago
QA Contact: nobody → stolenclover

Comment 7

15 years ago
even better, ->wontfix. As long as I'm involved in the release notes, they're
not going to docbook. sorry.
Status: NEW → RESOLVED
Last Resolved: 15 years ago
Resolution: --- → WONTFIX

Comment 8

15 years ago
gladly verifying
Status: RESOLVED → VERIFIED
(Assignee)

Updated

10 years ago
Product: mozilla.org → Websites
(Assignee)

Updated

6 years ago
Component: www.mozilla.org → General
Product: Websites → www.mozilla.org
You need to log in before you can comment on or make changes to this bug.