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:
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.