"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 or download 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
    3   errors.
    4 
    5 - Cygwin API docs update:
    6 
    7   - Either:
    8 
    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.
   12 
   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.
   17 
   18     - Or, move all SGML from winsup/cygwin into winsup/doc/api.
   19 
   20   - Current POSIX documentation is nonexistent.  Either:
   21 
   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.
   26 
   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.
   31 
   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.
   36 
   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.
   40 
   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.
   47 
   48 - Convert remaining code snippets from HTML entity form (&amp;,
   49   &lt;...)  to raw C/C++ code in CDATA sections.  Easier to read and
   50   edit in XML form.
   51 
   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.
   57 
   58 - Move to DocBook 5.
   59 
   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.
   66 
   67 - "Tidy" the XML files.
   68 
   69 - Remove --skip-validation from XMLTO flags variable in Makefile.in,
   70   then fix any errors and warnings that result.
   71 
   72 - Replace the hard-coded dates in <bookinfo><date> tags with DocBook
   73   time stamps.  (http://www.sagehill.net/docbookxsl/Datetime.html)
   74 
   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.
   78 
   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.
   82 
   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.
   86 
   87 - Typography improvements: curl all the quotation marks, replace "--"
   88   with em dashes, check proper names for missing accents, etc.
   89 
   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.)
   93 
   94 - Improve PDF styling:
   95 
   96   - Wider margins, section indenting, etc.  (i.e. Fix the "wall of text"
   97     problem.)
   98 
   99   - Current fonts are Business Blah at best.  Most severe to least:
  100 
  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.
  104 
  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?
  108 
  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.