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 -- http://linuxfromscratch.org/mailman/listinfo/hlfs-dev FAQ: http://www.linuxfromscratch.org/faq/ Unsubscribe: See the above information page
