"Fossies" - the Fresh Open Source Software Archive
Member "cygwin-snapshot-20210913-1/winsup/doc/Wishlist" (7 May 2021, 4773 Bytes) of package /windows/misc/cygwin-20210913-src-x86_64.tar.xz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard
) with prefixed line numbers.
Alternatively you can here view
the uninterpreted source code file.
1 - Change the '-' prefixes on Makefile.in commands to '@'. We only want
2 to avoid echoing the commands, not keep on trucking past build
5 - Cygwin API docs update:
7 - Either:
9 - Convert existing SGML code embedded in Cygwin source code
10 to Doxygen format, then set up HTML and PDF reference manual
11 generation in doc/Makefile.in. Then, remove vestiges of doctool.
13 The Cygwin User Manual reportedly references pieces of the
14 current SGML that makes up the API Manual, which if true means
15 we have a challenge to make the Doxygen process continue to feed
16 the user manual.
18 - Or, move all SGML from winsup/cygwin into winsup/doc/api.
20 - Current POSIX documentation is nonexistent. Either:
22 - Fork the current POSIX/Linux manpages. Downside of this is that
23 it's in nroff format and the license demands that nroff sources
24 continue to be made available. This is a challenge for PDF
25 manual integration.
27 - Switch to Doxygen, which lets us have skeletal POSIX docs almost
28 for free. Each can point to web docs for more complete info, such
29 that the Cygwin man pages only need to provide parameter lists and
30 document Cygwinisms in the implementation.
32 - Write our own man pages in DocBook <refentry> form. Such files
33 should be XInclude-able in regular API/user manuals, and only have
34 to have the same mininal info as in the Doxygen case above. It
35 just requires a more verbose markup format.
37 - Remove autotools outputs from repo. (configure, Makefile, etc.)
38 Create a bootstrap script to generate them. Make sure top-level
39 "make" process knows how to call the bootstrap script at need.
41 - There are absolute HTTP <ulinks> which should be transformed to
42 relative links so that they do the right thing when you move the docs
43 around. Maybe they'll never live somewhere else on cygwin.com, but if
44 nothing else, they currently do the wrong thing when you open one of the
45 generated .html files from the local filesystem: hyperlinks take you off
46 to cygwin.com instead of to the relevant local file.
48 - Convert remaining code snippets from HTML entity form (&,
49 <...) to raw C/C++ code in CDATA sections. Easier to read and
50 edit in XML form.
52 - Pretty code snippets. Search for a DocBook aware automatic code
53 formatter that will take raw example code in and mark it up, as exists
54 for HTML. If one can't be found or created -- e.g. by lashing an HTML
55 code formatter to a sed script then whipping them until they sing -- do
56 the markup by hand.
58 - Move to DocBook 5.
60 - Files are often named with less detail than the ID of the top-level
61 XML element it contains. For example, specialnames.xml contains
62 <sect1 id="using-specialnames">. The ID scheme seems hierarchical, so
63 maybe the files should go into subdirectories; e.g.
64 using/specialnames.xml. This would help with the proliferation of files
65 this "patch" created.
67 - "Tidy" the XML files.
69 - Remove --skip-validation from XMLTO flags variable in Makefile.in,
70 then fix any errors and warnings that result.
72 - Replace the hard-coded dates in <bookinfo><date> tags with DocBook
73 time stamps. (http://www.sagehill.net/docbookxsl/Datetime.html)
75 - cygwin-ug-net/cygwin-ug-net-nochunks.html.gz build rules can probably
76 be reduced to a one-liner by moving from xmlto wrapper to a raw
77 xsltproc call.
79 - Is xmlto pulling its own weight for the HTML case? It *might* have
80 some value for the PDF-via-dblatex case, but an xsltproc call for HTML
81 is also a one-liner.
83 - Switch from xmlto/dblatex to xsltproc/FOP for PDF? Might be a
84 prerequisite to the font changes below if dblatex doesn't allow
85 one to specify fonts through the xmlto layer.
87 - Typography improvements: curl all the quotation marks, replace "--"
88 with em dashes, check proper names for missing accents, etc.
90 - Adapt top-level cygwin.com CSS to DocBook HTML output so the user
91 guide blends with the rest of the site. (Something like this has
92 been done to cygwin.com/faq.html already.)
94 - Improve PDF styling:
96 - Wider margins, section indenting, etc. (i.e. Fix the "wall of text"
99 - Current fonts are Business Blah at best. Most severe to least:
101 - Courier for code is just plain ugly, and is apparently a bitmap
102 font in some people's PDF output besides. Switch to Deja Vu,
103 Inconsolata, or Adobe Source Code Pro.
105 - Times. Sigh. There must be something better in the free world,
106 something more in the Palatino or Garamond mold. Bitstream Vera
107 Serif? Linux Libertine?
109 - Arial/Helvetica/whatever. Not a serious issue, but we can do
110 better, even if it's just a minor shake-up, like switching to a
111 condensed face.