[RFC] Documentation tree sub-directories reorg.

[RFC] Documentation tree sub-directories reorg.

[Randy Dunlap]

Hi,

I would like to use a few more sub-directories in the Documentation/ tree to
try to help clean it up some.  E.g., move some drivers/block/ doc files to
Documentation/blockdev/ and move some serial/tty/chardev doc files to
Documentation/serial/  (or serial-tty/ or chardev/ or <suggestions>).


A [git] diff for blockdev/ and serial/ looks like:

 Documentation/00-INDEX                      |   38 +-------------------------
 Documentation/blockdev/00-INDEX             |   16 +++++++++++
 Documentation/{ => blockdev}/README.DAC960  |    0 
 Documentation/{ => blockdev}/cciss.txt      |    0 
 Documentation/{ => blockdev}/cpqarray.txt   |    0 
 Documentation/{ => blockdev}/floppy.txt     |    0 
 Documentation/{ => blockdev}/nbd.txt        |    0 
 Documentation/{ => blockdev}/paride.txt     |    0 
 Documentation/{ => blockdev}/ramdisk.txt    |    0 
 Documentation/serial/00-INDEX               |   24 +++++++++++++++++
 Documentation/{ => serial}/README.cycladesZ |    0 
 Documentation/{ => serial}/computone.txt    |    0 
 Documentation/{ => serial}/digiepca.txt     |    0 
 Documentation/{ => serial}/hayes-esp.txt    |    0 
 Documentation/{ => serial}/moxa-smartio     |    0 
 Documentation/{ => serial}/riscom8.txt      |    0 
 Documentation/{ => serial}/rocket.txt       |    0 
 Documentation/{ => serial}/specialix.txt    |    0 
 Documentation/{ => serial}/stallion.txt     |    0 
 Documentation/{ => serial}/sx.txt           |    0 
 Documentation/{ => serial}/tty.txt          |    0 
 21 files changed, 42 insertions(+), 36 deletions(-)
 create mode 100644 Documentation/blockdev/00-INDEX
 rename Documentation/{ => blockdev}/README.DAC960 (100%)
 rename Documentation/{ => blockdev}/cciss.txt (100%)
 rename Documentation/{ => blockdev}/cpqarray.txt (100%)
 rename Documentation/{ => blockdev}/floppy.txt (100%)
 rename Documentation/{ => blockdev}/nbd.txt (100%)
 rename Documentation/{ => blockdev}/paride.txt (100%)
 rename Documentation/{ => blockdev}/ramdisk.txt (100%)
 create mode 100644 Documentation/serial/00-INDEX
 rename Documentation/{ => serial}/README.cycladesZ (100%)
 rename Documentation/{ => serial}/computone.txt (100%)
 rename Documentation/{ => serial}/digiepca.txt (100%)
 rename Documentation/{ => serial}/hayes-esp.txt (100%)
 rename Documentation/{ => serial}/moxa-smartio (100%)
 rename Documentation/{ => serial}/riscom8.txt (100%)
 rename Documentation/{ => serial}/rocket.txt (100%)
 rename Documentation/{ => serial}/specialix.txt (100%)
 rename Documentation/{ => serial}/stallion.txt (100%)
 rename Documentation/{ => serial}/sx.txt (100%)
 rename Documentation/{ => serial}/tty.txt (100%)


Comments/thoughts?

Thanks,
~Randy
[The git tree is not currently on a shared system.]

Re: [RFC] Documentation tree sub-directories reorg.

[Jonathan Corbet]

On Tue, 04 Nov 2008 14:50:36 -0800
Randy Dunlap <rdunlap@xenotime.net> wrote:

> I would like to use a few more sub-directories in the Documentation/
> tree to try to help clean it up some.  E.g., move some drivers/block/
> doc files to Documentation/blockdev/ and move some serial/tty/chardev
> doc files to Documentation/serial/

This all makes fine sense to me, but I do wonder if we shouldn't also
create an "obsolete" subdirectory and put some of those files there?
For example, paride.txt starts off this way:

	Owing to the simplicity and near universality of the parallel port
	interface to personal computers, many external devices such as
	portable hard-disk, CD-ROM, LS-120 and tape drives use the parallel
	port to connect to their host computer.

Said ports are not quite as universal as they once were.  The document also
points to a nonexistent web page and a dead mailing list.  It's hard to
imagine that it's actually doing anybody any good at all.  Even if somebody
out there is still using the paride drivers (can there possibly be?), they
aren't likely to be getting much help here.

jon

Re: [RFC] Documentation tree sub-directories reorg.

[Rob Landley]

On Tuesday 04 November 2008 16:50:36 Randy Dunlap wrote:
> Hi,
>
> I would like to use a few more sub-directories in the Documentation/ tree
> to try to help clean it up some.  E.g., move some drivers/block/ doc files
> to Documentation/blockdev/ and move some serial/tty/chardev doc files to
> Documentation/serial/  (or serial-tty/ or chardev/ or <suggestions>).
>
>
> A [git] diff for blockdev/ and serial/ looks like:
...
> Comments/thoughts?

That's a good start.  It would also be nice to create an "arch" subdirectory 
to move the arm, m68k, mips, blackfin, parisc, powerpc, s390, sparc, ia64, 
uml, and x86 directories into.  (Plus sgi-*, voyager.txt, zorro.txt...)

Rob

Re: [RFC] Documentation tree sub-directories reorg.

[Rob Landley]

On Tuesday 04 November 2008 17:23:45 Jonathan Corbet wrote:
> On Tue, 04 Nov 2008 14:50:36 -0800
>
> Randy Dunlap <rdunlap@xenotime.net> wrote:
> > I would like to use a few more sub-directories in the Documentation/
> > tree to try to help clean it up some.  E.g., move some drivers/block/
> > doc files to Documentation/blockdev/ and move some serial/tty/chardev
> > doc files to Documentation/serial/
>
> This all makes fine sense to me, but I do wonder if we shouldn't also
> create an "obsolete" subdirectory and put some of those files there?
> For example, paride.txt starts off this way:
>
> 	Owing to the simplicity and near universality of the parallel port
> 	interface to personal computers, many external devices such as
> 	portable hard-disk, CD-ROM, LS-120 and tape drives use the parallel
> 	port to connect to their host computer.
>
> Said ports are not quite as universal as they once were.

Yeah, but the robotics guys guys love 'em as a really easy way to get 
controllable pinouts from PC hardware. :)

No objection to the idea of a place to put obsolete docs, 
although "deprecated" might be a better name and it seems like it relates to 
feature-removal-schedule.txt somehow...

Rob

Re: [RFC] Documentation tree sub-directories reorg.

[J. Bruce Fields]

On Fri, Nov 07, 2008 at 01:13:49PM -0600, Rob Landley wrote:
> On Tuesday 04 November 2008 16:50:36 Randy Dunlap wrote:
> > Hi,
> >
> > I would like to use a few more sub-directories in the Documentation/ tree
> > to try to help clean it up some.  E.g., move some drivers/block/ doc files
> > to Documentation/blockdev/ and move some serial/tty/chardev doc files to
> > Documentation/serial/  (or serial-tty/ or chardev/ or <suggestions>).
> >
> >
> > A [git] diff for blockdev/ and serial/ looks like:
> ...
> > Comments/thoughts?
> 
> That's a good start.  It would also be nice to create an "arch" subdirectory 
> to move the arm, m68k, mips, blackfin, parisc, powerpc, s390, sparc, ia64, 
> uml, and x86 directories into.  (Plus sgi-*, voyager.txt, zorro.txt...)

I started doing some of this here:

	git://linux-nfs.org/~bfields/linux.git for-joncorbet

but didn't get very far.  (But in the remote chance there's something
useful there, feel free to cannibalize it.)

--b.