diff options
Diffstat (limited to 'winsup/doc/Wishlist')
| -rw-r--r-- | winsup/doc/Wishlist | 111 |
1 files changed, 0 insertions, 111 deletions
diff --git a/winsup/doc/Wishlist b/winsup/doc/Wishlist deleted file mode 100644 index 9e7aa4ca1..000000000 --- a/winsup/doc/Wishlist +++ /dev/null @@ -1,111 +0,0 @@ -- Change the '-' prefixes on Makefile.in commands to '@'. We only want - to avoid echoing the commands, not keep on trucking past build - errors. - -- Cygwin API docs update: - - - Either: - - - Convert existing SGML code embedded in Cygwin source code - to Doxygen format, then set up HTML and PDF reference manual - generation in doc/Makefile.in. Then, remove vestiges of doctool. - - The Cygwin User Manual reportedly references pieces of the - current SGML that makes up the API Manual, which if true means - we have a challenge to make the Doxygen process continue to feed - the user manual. - - - Or, move all SGML from winsup/cygwin into winsup/doc/api. - - - Current POSIX documentation is nonexistent. Either: - - - Fork the current POSIX/Linux manpages. Downside of this is that - it's in nroff format and the license demands that nroff sources - continue to be made available. This is a challenge for PDF - manual integration. - - - Switch to Doxygen, which lets us have skeletal POSIX docs almost - for free. Each can point to web docs for more complete info, such - that the Cygwin man pages only need to provide parameter lists and - document Cygwinisms in the implementation. - - - Write our own man pages in DocBook <refentry> form. Such files - should be XInclude-able in regular API/user manuals, and only have - to have the same mininal info as in the Doxygen case above. It - just requires a more verbose markup format. - -- Remove autotools outputs from repo. (configure, Makefile, etc.) - Create a bootstrap script to generate them. Make sure top-level - "make" process knows how to call the bootstrap script at need. - -- There are absolute HTTP <ulinks> which should be transformed to - relative links so that they do the right thing when you move the docs - around. Maybe they'll never live somewhere else on cygwin.com, but if - nothing else, they currently do the wrong thing when you open one of the - generated .html files from the local filesystem: hyperlinks take you off - to cygwin.com instead of to the relevant local file. - -- Convert remaining code snippets from HTML entity form (&, - <...) to raw C/C++ code in CDATA sections. Easier to read and - edit in XML form. - -- Pretty code snippets. Search for a DocBook aware automatic code - formatter that will take raw example code in and mark it up, as exists - for HTML. If one can't be found or created -- e.g. by lashing an HTML - code formatter to a sed script then whipping them until they sing -- do - the markup by hand. - -- Move to DocBook 5. - -- Files are often named with less detail than the ID of the top-level - XML element it contains. For example, specialnames.xml contains - <sect1 id="using-specialnames">. The ID scheme seems hierarchical, so - maybe the files should go into subdirectories; e.g. - using/specialnames.xml. This would help with the proliferation of files - this "patch" created. - -- "Tidy" the XML files. - -- Remove --skip-validation from XMLTO flags variable in Makefile.in, - then fix any errors and warnings that result. - -- Replace the hard-coded dates in <bookinfo><date> tags with DocBook - time stamps. (http://www.sagehill.net/docbookxsl/Datetime.html) - -- cygwin-ug-net/cygwin-ug-net-nochunks.html.gz build rules can probably - be reduced to a one-liner by moving from xmlto wrapper to a raw - xsltproc call. - -- Is xmlto pulling its own weight for the HTML case? It *might* have - some value for the PDF-via-dblatex case, but an xsltproc call for HTML - is also a one-liner. - -- Switch from xmlto/dblatex to xsltproc/FOP for PDF? Might be a - prerequisite to the font changes below if dblatex doesn't allow - one to specify fonts through the xmlto layer. - -- Typography improvements: curl all the quotation marks, replace "--" - with em dashes, check proper names for missing accents, etc. - -- Adapt top-level cygwin.com CSS to DocBook HTML output so the user - guide blends with the rest of the site. (Something like this has - been done to cygwin.com/faq.html already.) - -- Improve PDF styling: - - - Wider margins, section indenting, etc. (i.e. Fix the "wall of text" - problem.) - - - Current fonts are Business Blah at best. Most severe to least: - - - Courier for code is just plain ugly, and is apparently a bitmap - font in some people's PDF output besides. Switch to Deja Vu, - Inconsolata, or Adobe Source Code Pro. - - - Times. Sigh. There must be something better in the free world, - something more in the Palatino or Garamond mold. Bitstream Vera - Serif? Linux Libertine? - - - Arial/Helvetica/whatever. Not a serious issue, but we can do - better, even if it's just a minor shake-up, like switching to a - condensed face. |