From d46cc674ec2e05cb90c8813bdb964b990201ac35 Mon Sep 17 00:00:00 2001 From: Warren Young Date: Mon, 13 May 2013 22:00:44 +0000 Subject: [PATCH] Added Wishlist file, based on my FURTHER WORK proposal to the -patches list on April 29. --- winsup/doc/ChangeLog | 2 + winsup/doc/Wishlist | 114 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 116 insertions(+) create mode 100644 winsup/doc/Wishlist diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index 769aa025a..3b33c631a 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,6 +1,8 @@ 2013-05-13 Warren Young * cygwin-ug.xml setup.xml: Removed; unused. + * Wishlist: Created, with initial content based on a -patches + mailing list post. 2013-05-06 Warren Young diff --git a/winsup/doc/Wishlist b/winsup/doc/Wishlist new file mode 100644 index 000000000..44aa26b6e --- /dev/null +++ b/winsup/doc/Wishlist @@ -0,0 +1,114 @@ +- Change the '-' prefixes on Makefile.in commands to '@'. We only want + to avoid echoing the commands, not keep on trucking past build + errors. + +- Find/build XInclude-aware automatic Makefile dependency generator. At + worst, this shouldn't be much more than a bit of shell and sed. + +- 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 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 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 + . 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 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.