NetBSD-Docs archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

looking for feedback about NetBSD documentation for printed books

I will be creating book-ready PDFs of NetBSD documentation and book covers 
and submit to a print-on-demand service. If enough interest I may also 
assign an ISBN (I already purchased them) and submit to printer and 
distributor for wider distribution (like Amazon and Barnes and Noble).

The initial plan is to make the books like the 1994 Usenix print book 
volumes of the 4.4BSD docs. For example, these contain:

User's Reference Manual (URM) -- 898 pages
 - list of developers and organizations
 - preface -- about 4.4BSD changes
 - introduction: about the books, "How to get started" (logging in, etc)
 - list of manual pages with header description for all sections
 - Permuted Index (which still seems confusing and not extremely useful to me)
 - section 1 man pages: intro, adb through znew
 - section 6 man pages: adventure through xroach
 - section 7 man pages: intro, ascii through term(7)

System Manager's Manual (SMM) -- 646 pages
 - table of contents
 - introduction: about the books
 - list of manual pages with header description for all sections   
 - Permuted Index
 - section 8 man pages: intro, ac through zic
 - System Management Documents 1 (installing and operating 4.4BSD) through 
   19 (perl)

NetBSD's src/share/doc/smm only has 04.quotas 06.nfs 01.setup 
05.fastfs 17.password and config (was 2).

User's Supplementary Documents (USD) -- 686 pages
 - table of contents
 - USD documents 1 (UNIX For Beginners) through 31 (Star Trek)

NetBSD's src/share/doc/usd only has 01.begin 17.msmacros 18.msdiffs 
19.memacros 20.meref

Programmer's Reference Manual (PSD) -- 868 pages
 - table of contents
 - introduction: about the books
 - list of manual pages with header description for all sections   
 - Permuted Index
 - section 2 man pages: intro, accept through write(2)
 - section 3 man pages: intro, abort through vtimes(3)
 - section 4 man pages: intro, netintro(4), autoconf through utf2
 - section 5 man pages: a.out through vgrindefs

Programmer's Supplementary Documents (PSD) -- 606 pages
 - table of contents
 - introduction: about the books
 - PSD documents 1 (Ritchie and Thompson's 1974 "The UNIX Time-Sharing 
   System") through 21 (Advanced 4.4BSD IPC Tutorial)

NetBSD's src/share/doc/psd only has 05.sysman 20.ipctut 21.ipc

My questions:

1) I want to title the books with "NetBSD" instead of "4.4BSD". Should I 
include or exclude the historical, out-of-date 4.4BSD documents?

2) Should I attempt to update 4.4BSD documents? (Seems like a huge amount 
of work.)

3) Should I hunt down the historical documents? (Usenix received 
permission from AT&T in 1994 or previously.)

I don't know yet if we have all imported that we have access too. See (I didn't 
look yet at that)

4) We have many new manual pages. For example the 1994 System Manager's 
Manual is 606 pages. Probably about a 3rd of that is the section 8 manual 
pages. But section 8 manual pages for NetBSD is over 1200 pages long (I 
had 1309). Just Postfix's man8 is 104 printed pages, lvm's man8 is 60 
pages, And openldap's man8 is 36 pages. The pppd man8 pages is 39 pages 
long. tcpdump is 23 pages. pam in man8 is 29 pages. puffs are 16 pages.

I could easily create two volumes of the section 8 man pages. So the 
System Manager's Manual (SMM) would become two volumes. Is that okay?

I thought I can do Programmer's Reference Manual (PSD) the easiest since 
it is just permuted index and man pages. But recent section 2 is 297 
pages, section 3 is 2025 pages (looks like 376 pages for libcrypto or 
ssl), section 4 is 1320 pages, and section 5 is 1060 pages. This would 
take many books.

5) Should I split up or exclude certain software? Like Postfix manpages 
for all sections is 220 pages.

6) I don't like how old books don't have running page numbers (they 
reset/restart at one frequently). I plan on fixing that. Or do you prefer 
documents and man pages being numbered starting from 1?

7) security(8) is in the wrong section. I brought this up before. Okay to 
move to section 7?

8) The old books have different BSD versions in bottom left footer of man 
pages. I am guessing that is when last updated. But when I generate I 
think I'd have all say NetBSD 5.0 -- any thoughts on that?

9) Maybe I should use our updated docs from htdocs instead. But I think 
someone else may have been working on that. What do you think of some 
parts of htdocs for printed book(s)?

10) What is the most doable or most interesting part to provide a printed 
book first?

11) any advice or suggestions?

  Jeremy C. Reed

p.s. I also saw hubert had generated PDFs of man pages a couple months 

Home | Main Index | Thread Index | Old Index