112 lines
4.7 KiB
Plaintext
112 lines
4.7 KiB
Plaintext
|
- 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.
|