discuss: proposed outline: Author Guide
Subject:
Re: proposed outline: Author Guide
From:
Guillaume LELARGE ####@####.####
Date:
12 Jul 2003 16:13:55 -0000
Message-Id: <200307121815.17742.gleu@wanadoo.fr>
Le Mardi 8 Juillet 2003 14:56, Emma Jane Hogbin a écrit :
> On Tue, Jul 08, 2003 at 09:50:36AM -0400, Mark Komarinski wrote:
> > On Tue, Jul 08, 2003 at 03:57:17PM +0930, Glen Turner wrote:
> [...]
> > > What would be really nice list a huge section listing
> > > all the markup templates
>
> I have mixed feelings on this. I think if there were an LDP style guide
> that says "this is how we recommend you make a ***" then it would be
> useful. If it's just going to be a huge table without descriptions and
> context I don't think it's any more or less useful than what DocBook has
> already done themselves.
>
This is what the KDE team does for their own documentation. See
http://i18n.kde.org/doc/markup/index.html for more details.
Doing such a thing is really interesting IMHO 'cause DocBook has a really huge
number of tags and lowering it a bit could be something interesting.
> I think it would be useful is to look at document components and
> explain them. For the "code" bits I would give rationale on why it's used
> this way. For the "before" stuff I would simply give a "this is how we do
> it" explanation. As an author I could also then use it as a checklist to
> make sure I had all of the correct bits (Tabatha had to re-write most of
> my "before" content because it wasn't in the right format, although it
> validated as DocBook).
> e.g. (much of this is already in the table listing)
> before: author info, dates, versions, copyright etc
> content: lists, paragraphs, sections, application
> asides: warning, note, tip
> commands: userinput, parameter, option
> display: screen
> references: sample of how to make a bibliography, link within a
> document
> after: license, appendix
>
> > A lot of this has already been done. Either by purchasing DocBook: TDG,
> > or by looking at it online (http://www.docbook.org/tdg/en/). When I
> > wrote the LAG, I didn't want to duplicate a lot of effort, mostly because
> > I'm lazy.
>
> Forget about the lazy factor! The DocBook web site is really easy to use!
> The elements are cross-referenced and tell you what other things you
> should consider that are similar; it tells you what an element must
> contain; and what it may be contained in; and it tells you the attributes
> you can use. What the DocBook is lacking is good descriptions of when to
> use the elements--it's a little too flexible perhaps.
>
And perhaps less tags?
When I translate a HOWTO in french, I always put it in xml docbook format.
It's much easier to use with stylesheet.
Regards.
--
Guillaume <!-- http://absfr.tuxfamily.org/ -->.
