[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RE: Alsa sound mini-HOWTO maintenance
> -----Original Message-----
> From: Valentijn Sessink [mailto:[email protected]]
>
> The problem is that I'm seeing a whole lot of stuff that
> makes me wonder
> about the usefullness of the DocBook document, and I'm afraid to break
> things *or* encounter another "ok-now-we-changed-format-again"
> experience in the future.
Well, the DocBook versions that we provide are just a starting point,
they're not really good examples of DocBook. They can be used, but if you
want a much better document (from a markup standpoint), holler and we'll get
one of our DocBook Guru's to go through and send you an updated copy. They
can also work with you (via this list or email) to help you get up-to-speed
on DocBook.
> Could you please help me out with the following questions regarding
> http://www.ibiblio.org/pub/Linux/docs/HOWTO/mini/other-formats
> /docbook/Alsa-sound.sgml.gz
>
> - the header says <!DOCTYPE Article PUBLIC "-//Davenport//DTD DocBook
> V3.0//EN">, however, all LDP documents I read talk about Docbook 3.1,
> 4.0 or 4.1. Does this mean the translation is oldfashioned already?
The scripts that we use to convert to DocBook are a bit old. I'd recommend
that you use either
<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
or
<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
> - I have various ``sometext'' in my document - still there in the
> DocBook version. Is this still the correct way of using " in Docbook?
I prefer to use <quote>sometext</quote>, but either way should work fine (I
think)
> - How should I format the various commands in my document, so
> they look
> like
> http://ldp.nllgg.nl/LDP/LDP-Author-Guide/usingconventions.html? Is
> there a specific way to use a command in a sentence? I mean the
> following: I could say something like:
> ``to install, use the following command:
> bash$ command''
There are a couple of options, I guess. You can use "to install, use the
following command: <command> command" or you could use "to install, use the
following command:
<screen>
bash$ command
</screen>
You can get the complete DocBook SGML of the LAG from
http://cvsweb.linuxdoc.org/index.cgi/~checkout~/LDP/guide/docbook/LDP-Author
-Guide/LDP-Author-Guide.sgml?rev=1.12&content-type=text/plain
And a few other places.
> But sometimes I'd like to say something alike without the
> ephasis, like
> saying: ``if you use <command>somecommand</command> for
> command, it will
> work, too''. What should be the best tag to use in place of <command>?
Use command, as you're not marking the document for appearance, but rather
for content. The LDP highlights commands as part of our "style sheets". If
you don't think that's a good idea, we can see about changing it, but it
would be changed for the entire LDP collection, not just per-doc.
> - How about things like filenames, directory structures etc.,
> how should
> I format these, i.e. what tags to use?
<filename>/home/gleblanc/foo.c</filename>
<filename class="directory"></home/gleblanc</filename
> - how about lists of functionality, like the stuff in
> paragraph 5.3. It
> is now formatted as ``<screen>'' but I doubt this being right. I
> probably did this wrong while writing the HOWTO in sgml, but
> what should
> I use now?
I would use a variablelist
(http://www.DocBook.org/tdg/html/variablelist.html). From reading your doc,
that seems to be the best fit.
> - is the "_" thing necessary? Is there a list of such words
> somewhere?
I'd take the _ out, because of the way the new stylesheets change
things. If you don't agree with <variablelist> you can try using
<itemizedlist> with — instead of _. I'm not sure of an easy
reference to all of the entities, but I'll try to find one and let you know.
> - how about cross references. I now have stuff like
> ``id="backw-compat"'' in my document. Is this also the
> preferred way in
> Docbook, or is it simply there to retain backwards-compatibility with
> the old sgml-style Howto?
Sure, let me go look at your LinuxDoc document... Yeah, take a look at
http://www.DocBook.org/tdg/html/xref.html for some info on how to do that.
Make sure that you use id attributes on any sections that you want link to.
Like <sect1 id="whichModule"> and such.
> Then the final question. I'd like my document to actually be a kind of
> dynamic document, i.e. parse a couple of files to make the maintenance
> of the supported sound cards etc. easier. How should I do
> this? I master
> PHP a bit, is this a possible way of making it work? Like <?php
> parsefiletoincludelistofthings(); ?> and get the ``real'' DocBook
> document from my webserver? Or is this bad habit and should I use
> another method? The parsing would involve a couple of things: version
> number of the files I use; supported sound cards; maybe a FAQ-ish type
> of document. If I would be writing HTML, I would just do
> something like
> <?php $driverversion="alsa-0.1.2-drivers" ?> at the beginning of the
> document, and use a small file parsing loop to get the sound drivers.
> What is a good way to do this in DocBook?
If you keep that information in an external file, you can include it via an
entity. Use something like
<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"[
<!ENTITY alsa_drivers SYSTEM "alsa-0.1.2-drivers">
]>
And then in your document, use
&alsa_drivers;
where you want that text to appear. If I've misunderstood, let me know and
I'll get you a better answer.
> I hope you can cope with a clueless guy like me ;-)
Of course we can! Remember, we were all clueless at some point.
> If there are any mailinglists I should subscribe to, or if there's
> anything else I should do, please tell me so. However, I'm a
> HOWTO-writer and as such I do understand the value of DocBook, but
> trying to master it beyond simple cut&paste and organizing
> effort causes
> information overload at the moment. (Studying LDAP is enough
> conceptual
> thinking right now ;)
This is a good list to ask, IMHO. If we get stuck, most of us have some
other resources to call upon, and you can keep your mail volume down by just
sticking here. If you decided to pursue DocBook for more than just your
HOWTO, you might want to look at some other mailing lists.
BTW, when you submit the next version, could you send it as a full HOWTO?
Thanks,
Greg
--
To UNSUBSCRIBE, email to [email protected]
with a subject of "unsubscribe". Trouble? Contact [email protected]