[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: HOWTOs in DocBook SGML?
On Tue, 30 May 2000, Anthony E. Greene wrote:
> Does the LDP accept HOWTOs and mini-HOWTOs using the DocBook DTD?
Yes.
(BTW -- you're not living under a bridge somewhere in Norway are you?
Just wondering ... )
> I've read the HOWTO-HOWTO and the section on style is very brief. Is
> there more guidance on how a HOWTO should be structured?
No; but there should be.
In general, studying a few HOWTOs should give you a fair idea of what's
required:
* in your front matter <artheader>
you should probably have the following:
a title; <title>
the author(s); <author>
<firstname>
<surname>
[author's affiliation, if any]; <affiliation>
<orgname>
author's e-mail contact address; <address>
<email>
[other contributors]; <othercredit>
....
release/version info; <releaseinfo>
licensing blurb; <copyright>
<year>
<holder>
<legalnotice>
<para>
....
(brief) abstract <abstract>
<para>
....
* optional(?) keyword list in <keywordset>
<keyword>
* then in your main text body,
1st level header : Introduction <sect1><title>
<para>
2nd level header : - text changelog <sect2><title>
<para>
....
- where to get latest version <sect2 ...
....
- related documentation <sect2 ...
....
- etc...
1st level header : Chapter 2 <sect1><title>
<para>
2nd level header ........... <sect2><title>
<para>
....
3rd level header ........... <sect3><title>
<para>
....
1st level header : Chapter 3 <sect1><title>
<para>
....
etc., etc., etc.
* And then for your back matter, something like:
1st level header : Appendix A <sect1><title>
<para>
....
1st level header : Appendix B <sect1><title>
<para>
....
1st level header : References/Bibliography <sect1><title>
<biblioentry>
<citetitle>
<author>
<editor>
<isbn>
<abstract>
....
1st level header : Acknowledgements <sect1><title>
<para>
<listitem>
....
1st level header : Distribution and GPL (c) <sect1><title>
<para>
....
As for writing style -- whatever turns you on. Gertrude Stein? Terry
Pratchett? James Joyce? (Err ... maybe not, for newbies). Larry Wall?
Whatever it is, go for it.
Same as with any other writing task, actually -- screw the technique;
screw the structure; screw the method -- just concentrate on getting the
text down. _Your_ way.
If it's interesting, it'll be read.
(Oh -- and it'll be called a HOWTO; even if it's a 500-page novel; or a
2-page check-list. Sorry, but in this here project we only does HOWTOs :)
msw
--
Martin Wheeler - StarTEXT - Glastonbury - BA6 9PH - England
[1] mwheeler@startext.co.uk http://www.startext.co.uk/
[2] mwheeler@startext.f9.co.uk
"Real men only ever use vi.
Which is why publishing is now dominated by women."
--
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org