Future format of the book

Chris Buxton cbuxton at menandmice.com
Tue Jun 3 22:21:50 PDT 2008


You could use a CMS for this, where you maintain flat text files and  
it formats them as HTML. You could also probably use a wiki, so that  
the book could be edited collaboratively. A wiki with a comments  
system would seem to me to be the most useful way to go.

I used Dokuwiki from splitbrain.org to create my company's knowledge  
base.
http://www.splitbrain.org/projects/dokuwiki

Take a glance at this web page:
http://kbase.menandmice.com/kb/doku.php?id=kb:mmsuite:macosx:apple-named.conf

Now look at some snippets of the article source code:

The section at the top that starts with the header "Problem":
__________________________________________________________________________________

====== Problem ======

Starting in Mac OS X 10.2, Apple's major upgrade installers replace or  
change a key configuration file used by the Men & Mice DNS Server  
Controller. The file is ''/etc/named.conf'' - ''/etc'' is a hidden  
folder in Mac OS X's Finder.

If you've already tried reinstalling the Men & Mice Suite, or have  
tried to recreate your zones, you may have done further harm to your  
server.

However, it's all correctible. The instructions below are for Men &  
Mice Suite 5.1; for earlier versions, some of the commands will be  
slightly different.
__________________________________________________________________________________

A block of commands for the user to execute:
__________________________________________________________________________________

<code>sudo /Library/StartupItems/mmServerController/mmServerController  
restart
sudo launchctl unload /System/Library/LaunchDaemons/org.isc.named.plist
sudo launchctl load /System/Library/LaunchDaemons/org.isc.named.plist</ 
code>
__________________________________________________________________________________

Toward the bottom, there's a table:
__________________________________________________________________________________

Once again, use the following keystroke commands:

^ control-k | delete the line where the keyboard cursor is  |
^ control-o | save (and then enter to confirm the filename) |
^ control-x | exit                                          |
__________________________________________________________________________________

I can show you more if you like. And it's easy to attach downloadable  
files, such as patches or images, to a page.

This would allow you to basically stick to plain text, but anytime you  
want something fancier, you can break out into some mild coding.

Chris Buxton
Professional Services
Men & Mice


On Jun 3, 2008, at 7:08 PM, Robert Connolly wrote:

> Hello. Recently the lfs-dev mailing list seems to have decided to  
> flip from
> xml to php, and to add rpm spec files for all packages so that a  
> package
> manager can optionally be dropped in. Boot and Udev scripts have  
> also been
> integrated into the book.
>
> I may have mentioned it before... I hate xml. It's nice to look at  
> the html,
> it stores information well, but despite the generous help and  
> maintenance
> from Manuel, I hate maintaining an xml book and I seriously doubt I  
> will like
> php any better.
>
> I want to bring us back to 1969, with a plain text book. In a single  
> tarball
> have the book, boot scripts, maybe patches too, separated by  
> directories
> instead of links. Pages for packages can be written with #comments  
> so they
> can be run as shell scripts to install packages. Each package has a
> directory, with it's patches (if any), grsecurity policy for the  
> programs,
> and file lists for tripwire (and/or package manager).
>
> So the Inetutils package could have a chap6 directory like:
>
> chap6/inetutils
> chap6/inetutils/chap6-inetutils.txt (shell script)
> chap6/inetutils/inetutils-1.5-fixes-2.patch
> chap6/inetutils/ftp.grsec_policy
> chap6/inetutils/ping.grsec_policy
> chap6/inetutils/talk.grsec_policy
> chap6/inetutils/telnet.grsec_policy
> chap6/inetutils/tftp.grsec_policy
> chap6/inetutils/inetutils.docfiles_list
> chap6/inetutils/inetutils.programs_list
> chap6/inetutils/inetutils.libraries_list
>
> Or some variation of this. This is the most robust approach I see.  
> It has what
> everyone needs, maybe not in the way they want it but in a way that's
> perfectly usable.
>
> A book like this would make me much much happier. It's easy to  
> maintain, and
> practical. It's not very easy to read from an html browser, but  
> maybe a
> simple index.html page could be done to keep things browsable, and  
> easy on
> svn if a new package is added or if packages are moved around.
>
> The way I have been editing xml, with Vim, is extremely prone to  
> errors. The
> pages are not usable, easily, as scripts. And adding more stuff like  
> file
> lists will just make things worse. Xml is perfectly capable of  
> handling all
> of this, but it's overkill and I'm more happy as a system developer  
> than a
> book developer (I do not want to learn xml).
>
> I know a lot of people will not like a flip to plain text, and to be  
> honest
> that doesn't bother me one bit. If anyone has a suggestion that  
> doesn't
> involve me or other editors taking a six month course in web  
> programing then
> I would like to hear it.
>
> This idea is harder on book readers and users, and easier on  
> editors, which is
> less efficient, but I think it's a fair compromise if extra hours  
> are spent
> on systems development.
>
> I want to thank Manuel very very much for converting the original  
> plain text
> book to xml/html, and for doing ongoing maintenance and changes, but  
> I want
> to go back like it was originally. This has been bugging me for a  
> long time.
>
> I'm curious to hear opinions about this. My mind is open.
>
> robert
> -- 
> http://linuxfromscratch.org/mailman/listinfo/hlfs-dev
> FAQ: http://www.linuxfromscratch.org/faq/
> Unsubscribe: See the above information page




More information about the hlfs-dev mailing list