more defined process
Mark Johnson
mjohnson at redhat.com
Sat Aug 14 21:39:02 UTC 2004
Tammy Fox wrote:
> One of the benefits of
> DocBook is that you can use conditionals to create multiple documents
> from the same source (like I was saying with the Installation Guides for
> multiple arches in a different thread).
Yeah, but not within the docs themselves. With XML the conditionals
have to lie in the 'external subset', like a customization layer for
the DTD. (Unless I'm really confused about XML...)
> So, instead of creating a
> separate guide with some of the same information, I think we should use
> conditions in the existing source for the Docs Guide and create this
> Quick Start Guide instead, if it is determined that we need another one.
> This will make sure the 2 do not get out of sync, which can happen very
> quickly.
>
> Mark, since this is your idea, please share some more details about what
> you have in mind. How is it different from the existing guide?
It would be a very brief tutorial on how to configure emacs for
user-friendly DocBook XML editing. Naturally, I'd recommend that new
users make use of my psgmlx[1] package for the psgml setup. [May
have to do some tweaking to the package to provide the right stuff
in the "Insert DTD" menu. I'll look inot this. Karsten & I are
putting the package on Savannah 'real soon now'.]
> What problem does it solve?
Setting up emacsp/sgml, effectively, w/o having to do any setup.
Truly a quick start to setting up a DocBook authoring environment in
emacs. It's different from what's in the Docs guide in that psgmlx
does all the setup for you, and provides sgml/xml-mode color themes
as well. Put simply, it's aimed at newbie emacs users.
It could be called a "Quick Start Setup Guide for Authoring DocBook
docs with GNU Emacs", or something along those lines. The title
isn't that important to me so long as it conveys the content of the
document.
[1] http://dulug.duke.edu/~mark/psgmlx
> However, I would just like to
> point out that even if you have used DocBook before, things like tag
> usage can be interpreted in different ways, so you still need to read
> the guide to make sure you are following the same rules as everyone else
> writing Fedora docs.
I agree. Some people do need a sort of 'best practices' or 'our
practices' guide to tag usage, even though the online "DocBook, The
Definitive Guide" is usually sufficient. For example, the use of
'filename' to tag a package is not at all obvious, as one could also
use 'systemitem', or 'application', or many other things. So, yeah,
I agree that there needs to be some sort of style guide to resolve
ambiguities of these sorts. [FWIW, DocBook V4.4 now has a 'package'
element, but is still only in the candidate release phase.]
> I honestly don't think it is that long or verbose.
It's long, but given the scope of the document, its length makes
sense. I still am of the opinion that <section> should be
recommended instead of the <sect1> <sect2>, etc. elements, and that
the ID naming convention needs to be overhauled. But, hey, that's
just my opinion:)
Cheers,
Mark
--
----------------------------------------------------------
Mark Johnson <mjohnson at redhat.com>
Red Hat Documentation Group <http://www.redhat.com>
Tel: 919.754.4151 Fax: 919.754.3708
GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242
More information about the fedora-docs-list
mailing list