discuss: Thread: [info] migration preparation; more output and source cleanup

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/

Le 02/02/2016 20:52, Martin A. Brown a écrit :
>
> Hello everybody,

Hello :-)

I won't comment on most of your posts, but I read them and agree with 
them :-)

thanks
jdd

> Working on the cleanup of the output tree has also caused me to 
> 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.
Good.  They will only be published on the master site and not the mirrors.
A major use of "retired" will be for historical purposes.  But even current
docs may want to mention history.  And a few might serve as examples we
shouldn't have accepted in the first place.  I recall that some
documents that had many errors were removed for review.  Maybe there should
have a "rejected" documents subtree.  One doc removed for review was mostly
plagiarized from the Inet but not marked as such.
			David Lawyer

>> Working on the cleanup of the output tree has also caused me to 
>> 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.

>Good.  They will only be published on the master site and not the 
>mirrors. A major use of "retired" will be for historical purposes.  
>But even current docs may want to mention history.  And a few might 
>serve as examples we shouldn't have accepted in the first place.  

OK.  We'll have a 'retired' section in the output tree (visible on 
the web).  I only created the 'retired' section of the source tree, 
but it's fine and easy.  The 'retired' documents will not be 
automatically updated.

>I recall that some documents that had many errors were removed for 
>review.  Maybe there should have a "rejected" documents subtree.  
>One doc removed for review was mostly plagiarized from the Inet but 
>not marked as such.

If we reject a document, why would we want to publish it under 
tldp.org?  I am not crazy about this idea.

Or do you mean that we should have a place in the source tree where 
we store the 'rejected' documents?

-Martin

-- 
Martin A. Brown
http://linux-ip.net/