gzip: Documentation not organized properly
Provides native Win32 open source ports and utilities
Brought to you by:
gnuwin32
Menu
▾
▴
#64 gzip: Documentation not organized properly
Documents found in Gzip packages are arranged in ways that are not logically organized, which undermines the usefulness of the manuals, and potentially burden the project with unnecessary support calls. For example:
-In the binary package, the documents are scattered in man and contrib/gzip/1.3.12/gzip-1.3.12-src directories.
-In the binary package, most of the files under contrib/gzip/1.3.12/gzip-1.3.12-src directory has nothing to do with compiling. In fact, it doesn't make sense to even have a source directory in a package with no source code, let alone putting files in that many directory levels.
-In the documentation package, not all documents are stored under the doc/ directory.
-In the documentation package, the info directory contains makeinfo version of the manual, which in itself is in text format. Since documentation package already has the same contents in text format in other directory, it is redundant.
-In the documentation package, the documents in doc/ directory are nested in 3 levels of directories with no files before getting to the actual directory with the documents. Unless Gzip document packages comes with non-Gzip manuals, that many levels of nesting are just too many to be sensible.
-In the documentation package, not all file formats include all documentations. For example, the .CHM, .HLP versions of the manuals do not include man page documentations, or any equivalent information for those file formats. Such information should be available in all file formats.
All documents, regardless of package, should use the same document organization hierarchy. In particular, all documentations should be put under doc/ directory. Package type specific information, such as change log, readme, to-do list, should be in the root of doc/ directory. Document in specific file format should be in its own directory. For example, doc/ps/ for PostScript manuals, doc/html/ for HTML manuals, doc/nroff for nroff manuals, and so on. File formats supporting navigation links (eg: .HLP, .CHM, PDF) should include all documentation in a single file per file format.
This concept should be expanded into a master package design, where a master package, which would include every file for a specific version of the project, put all the binaries in bin/ directory, documentation (including information on compiling source codes) in doc/ directory, source codes in src/ directory. That streamlines the package design from the messes in the current Gzip distributions.
Logged In: YES
user_id=217802
Originator: NO
Most of these items are feature requests, not bugs or messes; nor have there been any support calls. It has been transferred to the Feature Requests.