discuss: [info] migration preparation; more output and source cleanup
Subject:
[info] migration preparation; more output and source cleanup
From:
"Martin A. Brown" ####@####.####
Date:
2 Feb 2016 19:51:02 +0000
Message-Id: <alpine.LSU.2.11.1602021109580.2025@znpeba.jbaqresebt.arg>
Hello everybody,
This is a progress update on step 1 and step 3:
3. cleanup: Simplify, revise and prune the output tree.
cleanup: Source documents not in output tree
--------------------------------------------
Working on the cleanup of the output tree has also caused me to
conclude that some documents in our source repository have long been
retired. I therefore created a new directory called
LDP/LDP/retired/ which now contains any documents which should no
longer be published. I'm operating under the assumption that the
documents in the output tree represent the canonical set.
Newly retired documents (preceded by prior revision date):
----------------------------------------------------------
* (2000-Apr-26) Cyrillic-HOWTO
* (2003-Apr-24) Deciding-Linux-HOWTO
* (2002-Mar-04) Dialup-PPP-Server-HOWTO
* (2001-Dec-12) IPTables
* (2003-Jul-07) kde-compile
* (2004-May-13) Kernel-Build-HOWTO
* (2003-Jul-07) lamp
* (2001-Feb-14) Ldap-Implementation-HOWTO
* (2004-Jun-07) Linux-Daemon-HOWTO
* (2003-Nov-03) PLD-Guide
* (2004-Jul-02) Win+BSD+Linux-Install-HOWTO
The documentation included in the output tree also includes some documents for
which we do not appear to have source.
1. automation: Be able to (re-)process and (re-)publish all of
our existing documentation in an automated fashion.
automation: New output tree layout fragment:
--------------------------------------------
The layout I have chosen is based on an earlier volunteer's suggestion [0].
Current layout and formats: documents are in many different possible places
depending on whether the document is a HOWTO, a REF, an FAQ or a GUIDE
(capitalization does not appear to be consistent between input and output
trees, either). Also, the generated outputs differed, depending on the source
format.
Formats produced are:
---------------------
* HTML (.html)
* HTML single (-single.html)
* PDF (.pdf)
* text (.txt)
Filesystem layout produced (by document):
-----------------------------------------
Here is the output of the command 'tree' to show what the new tool [1] will
produce in the (automatically generated) output tree (I picked two HOWTOs at
random).
Large-Disk-HOWTO/ ZIP-Drive/
├── images ├── index.html -> ZIP-Drive.html
│ ├── MaxtorStyleA.gif ├── ZIP-Drive-1.html
│ ├── MaxtorStyleB.gif ├── ZIP-Drive-2.html
│ └── MaxtorStyleC.gif ├── ZIP-Drive-3.html
├── index.html -> Large-Disk-HOWTO.html ├── ZIP-Drive-4.html
├── Large-Disk-HOWTO-10.html ├── ZIP-Drive-5.html
├── Large-Disk-HOWTO-11.html ├── ZIP-Drive-6.html
├── Large-Disk-HOWTO-12.html ├── ZIP-Drive-7.html
├── Large-Disk-HOWTO-13.html ├── ZIP-Drive-8.html
├── Large-Disk-HOWTO-14.html ├── ZIP-Drive-9.html
├── Large-Disk-HOWTO-1.html ├── ZIP-Drive.html
├── Large-Disk-HOWTO-2.html ├── ZIP-Drive.pdf
├── Large-Disk-HOWTO-3.html ├── ZIP-Drive-single.html
├── Large-Disk-HOWTO-4.html └── ZIP-Drive.txt
├── Large-Disk-HOWTO-5.html
├── Large-Disk-HOWTO-6.html
├── Large-Disk-HOWTO-7.html
├── Large-Disk-HOWTO-8.html
├── Large-Disk-HOWTO-9.html
├── Large-Disk-HOWTO.html
├── Large-Disk-HOWTO.pdf
├── Large-Disk-HOWTO-single.html
└── Large-Disk-HOWTO.txt
The current output directory tree is labeled, variously, '/HOWTO/', '/LDP/',
'/FAQ/' and/or '/REF/'. I propose a layout like this:
http://www.tldp.org/en/<document_stem_name>/
http://www.tldp.org/en/Large-Disk-HOWTO/
http://www.tldp.org/en/ZIP-Drive/
I'd be glad to take any comments on the above. I'll send a separate email
with questions.
-Martin
[0] http://lists.tldp.org/go.to?list=discuss&cmd=showmsg&msgnum=382
This is a very old thread suggesting a single namespace for all
documents, rather than having them separated into Guide, FAQ and HOWTO,
especially given that there was no mapping from document class and type
(format) into this arbitrary classification. (From Patrick K. O'Brien)
We could reorganize the entire version control repository, but I don't
see the point. I do, however, see the point of producing all formats
into a single directory for each source document. (Main advantages:
easier to remove a single directory if/when a document is retired;
document can have links to ./resources/ and ./images/ underneath the
directory at which it is rooted; very predictable structure)
[1] https://github.com/martin-a-brown/LDP/blob/master/LDP/builder-2016/produce-ldp-outputs
https://github.com/martin-a-brown/LDP/blob/master/LDP/builder-2016/Makefile
--
Martin A. Brown
http://linux-ip.net/
