Bug 690274 - HTML coding and style guidelines for Ghostscript documentation was prematurely removed
Summary: HTML coding and style guidelines for Ghostscript documentation was prematurel...
Status: RESOLVED WONTFIX
Alias: None
Product: Ghostscript
Classification: Unclassified
Component: Documentation (show other bugs)
Version: 8.64
Hardware: All All
: P4 major
Assignee: Default assignee
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2009-02-06 19:06 UTC by goldart.geo
Modified: 2009-02-06 21:37 UTC (History)
0 users

See Also:
Customer:
Word Size: ---


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description goldart.geo 2009-02-06 19:06:50 UTC
In Ghostscript 8.64, the HTML coding and style guidelines for Ghostscript
documentation was removed from Ghostscript distribution.  From the 8.64 change log:

2008-08-27T02:16:43.113337Z Ralph Giles

Remove the obsolete HTML style guidelines.

We no longer expect readers to look at the raw html in a text editor.
Documentation should declare its format specification and conform to it,
attempting to match local style where appropriate.

[doc/Htmstyle.htm doc/Readme.htm]

Unfortunately, such decision leaves current Ghostscript manual devoid of any
styling guide on creating documentation, regardless of file format. Does that
mean it will become a free-for-all from now on? The removed guide is intended
primarily for documentation writer, not reader, so the reasoning for removal was
targeted at the wrong audience.

Wrong target aside, is the current Ghostscript's HTML manual even properly
formatted? The alternative to the current HTML coding and style guidelines was
posted in bug 688440, which was updated to accomodate CSS and international
encoding. Even though the updated guide was submitted into Bugzilla database
back in 2007, it was never included in subsequent Ghostscript distributions, and
the updated guide features has never been implemented in Ghostscript HTML manual
ever since. How can future Ghostscript users be assured that the future
Ghostscript manual won't turn into an useless, obsolete mess when the
alternative proposal was not implemented, and the existing guide was replaced by
some overly vague statements hidden in some change logs? And for that matter,
how do we expect people to RTFM before calling for support, when those who WTFM
are snubbed by higher level developers making shortsighted decisions?

HTML documentaion aside, it seems that is not the only file format current
Ghostscript manual is using. For those who actually read the HTML sources, they
should notice that certain portions of existing HTML documentations are
automatically generated, especially the change logs. That implies that the real
raw documention formats used to generate current Ghostscript HTML document are
simply undocumented, or at least incomplete, even before removing the guide.
Removing the HTML guide in such premature manner will only lead to chaos later
on from documentation contributors, who may submit documentations in proprietary
formats. Even by limiting contributions to HTML, the documentation styles used
by individual contributors can hinder the updating of the Ghostscript manual, if
Ghostscript package does not include any (enforced) styling guides.

Even if you don't care all the concerns mentioned above, the Readme.htm section
'What if I'm writing documentation?' still leaves an ugly cut off after removing
the guide from Ghostscript package, which is not even a decent editing job. That
only suggests the whole guide removal was done in haste instead of careful
planning, and definitely not by necessity.
------------------------------------------------------------------------
Ghostscript version (or include output from "gs -h"): 8.64
------------------------------------------------------------------------
Where you got Ghostscript: Ghostscript.com
------------------------------------------------------------------------
Hardware system you are using (including printer model if the problem
involves printing):

Memory: 384MB
CPU: Intel Pentium II 400
Sound: ESS Solo-1
Video: Neomagic MagicMedia 256AV
------------------------------------------------------------------------
Operating system you are using: Windows 98SE
------------------------------------------------------------------------
Suggested fix, if any:

The HTML coding and style guidelines for Ghostscript documentation should be put
back into Ghostscript packages, just because the reasoning given in the change
log was targeted at the wrong audience. Although the change log raised
legitimate concern that readers today are not likely to look at the raw html in
a text editor as it was in the past, removing the whole HTML coding and style
guidelines is a mistake. Many WYSIWYG HTML editors generate bloated and possibly
non-compliant codes, which can lead to other unforseen errors when other
documentation writers use different HTML editors. Also, as mentioned in above
segments, current Ghostscript manual does not even document all the file formats
used into creating the manual found in the final builds of Ghostscript packages.

Therefore, HTML coding and style guidelines for Ghostscript documentation should
not even be considered for removal until all the followings are done:

- Documenting all the file and file formats used into creating the manual found
in the final builds of Ghostscript packages
- Ghostscript developers explicit declare the primary file formats to be
expected by documentation contributors
- Generalized, format-independent Ghostscript documentation styling guide is in
place
- Coding and style guides for all the file and file formats used into creating
the manual found in the final builds of Ghostscript packages are in place
- HTML style guidelines focusing on converting raw Ghostscript documentation
formats into HTML and CSS formats is in place

However, since the mistake of removing HTML coding and style guidelines for
Ghostscript documentation had been made, the next best thing to do right now is
to immediately put the guide back into the next iteration of Ghostscript
packages. However, the guide that will be put back into Ghostscript package
should be the updated version, as posted in bug 688440.

After this issue is settled, let's move on to a longer term issue. The current
HTML coding and style guidelines, even the updated one, assume HTML file format
is used internally at the source level, and is the only file format to be used
in the manual inside binary Ghostscript packages. However, it really isn't the
case at source level, and probably will not be the case for manuals in future
Ghostscript packages. Therefore, a long term solution is to create a
generalized, file format-independent Ghostscript documentation styling guide,
while the existing HTML coding and style guidelines will be rewritten to focus
on how to convert the raw Ghostscript documentation formats into HTML and CSS
formats.

In the general documentation styling guide, the guide must include:
- The goal of the documentation styling guide. It can be adapted from existing
HTML coding and style guidelines for Ghostscript documentation, but rewritten to
be format-independent.
- The overall document structures
- Links to all supported file formats used by Ghostscript manual. It must
include the raw formats used into creating the manual found in the final builds
of Ghostscript packages, and HTML+CSS (for legacy support).

In a file format specific coding and style guide, the guide must include:

- Minimum version(s) of the supported file format(s). Proprietary extensions
must be avoided.
- Recommended application(s) to generate compliant document format(s).
------------------------------------------------------------------------
Other comments:
Comment 1 Ralph Giles 2009-02-06 21:37:14 UTC
The html style guide was primarily oriented to specifying a format that could be
parsed by web browsers while still being somewhat accessible to humans reading
the files in a text editor. This is the requirement I relaxed.

So yes, it is a free for all. As you noticed our documentation doesn't get much
attention, so I don't expect clashes between all the people trying to maintain
these files to be a problem.

If you're volunteering, then lets talk about what should be done. As it is, I
think it's nice if we provide html documentation, and I think it would be good
if it were (a) conforming html and (b) themed to match the website.