[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Alsa sound mini-HOWTO maintenance
Hello all,
I'm having a slight problem maintaining my Alsa sound howto, since the
transition from SGML to XML/DocBook. The problem lies in the fact that
I'm not a DocBook expert - and actually, don't want to become one.
However, I think I'm going to need to write (or maintain) Docbook to
maintain my HOWTO.
Naturally, I can just look in the kindly translated DocBook-source and
add any text I want to add.
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.
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?
- I have various ``sometext'' in my document - still there in the
DocBook version. Is this still the correct way of using " in Docbook?
- 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''
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>?
- How about things like filenames, directory structures etc., how should
I format these, i.e. what tags to use?
- 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?
- is the "_" thing necessary? Is there a list of such words
somewhere?
- 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?
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?
I hope you can cope with a clueless guy like me ;-)
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 ;)
Best regards,
Valentijn
--
Valentijn Sessink - valentyn@nospam.openoffice.nl
-
Open Office - Linux for the desktop - www.openoffice.nl
--
To UNSUBSCRIBE, email to ldp-docbook-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org