[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Authorship
Hi all,
I started to read Gary's HOWTO and here is what I think of it, section by
section:
Overview: I would keep it.
LDP: Mark's is better. A little history or explanation never hurts.
SGML: I think it should be emphasized that SGML is not a language itself
but rather a metalanguage in which you can define concrete languages.
The DocBook DTD is a document description language, while the HTML DTD is a
mixture of structure and format. Perhaps a small list of DocBook elements
(such as Command, Filename, Parameter, etc.) would make it easier to
understand that a DocBook document contains (at least, can contain)
information rather than pure formatted text.
Also, if we mentioned XML here (perhaps writing SGML/XML instead of SGML),
I am sure nobody would complain about the requirement of using it.
Getting acquianted with LDP: the archive of the ldp-discuss list could also
be mentioned.
Proposing a HOWTO: the link
"http://www.LinuxDoc.org/HOWTO/HOWTO-INDEX-3.html#ss3.1"; should point directly
to http://metalab.unc.edu/pub/Linux/docs/HOWTO/unmaintained/.
Also, studying DocBook HOWTOs is only useful if they are not automatically
converted from the LinuxDoc version. As long as the majority of the HOWTOs
are still in LinuxDoc, perhaps Stein's DocBook template would be of greater
help.
SGML tools: the second paragraph here, I think, is needless. If a prospective
LDP author does not know how to download files from the Internet, then he/she
has much to learn before qualifying for an author. I also do not understand
what "If [...] your preferred operating system is Linux" means: what else
would it be?
I do not think we should recommend tools but rather list them. I
particularly do not like the conclusion: if you have money and you also have
Windows, use WordPerfect. Let the author decide what he/she likes.
(By the way, if you have money and Windows, you can choose from professional
SGML/XML editors - XMetaL from SoftQuad is one.)
If we still want to recommend tools, the order should be:
open source tools on Linux,
free tools on Linux,
commercial tools on Linux,
the rest.
Why? Because we are doing Linux here.
vi is definitely also an option. Lyx, on the other hand, is not, if you are
serious about DocBook, because it only supports a handful of DocBook
elements.
sgedit (http://www.tksgml.de) is also free for personal use, but it is beta
and has a couple of bugs.
Things will definitely change when we move to XML: we will have more tools.
Jade, DSSSL, DocBook 3.1 DTD: RedHat 6.2 and Caldera 2.4 Desktop (probably
most newer distributions as well) contain these packages.
sgmltools: I do not think you actually need this software.
TeX: there is a LaTeX-to-HTML converter somewhere on the Net (not that it
mattered much). If I am not mistaken, TeX is only needed if you want to use
Jade
to convert an SGML document to PostScript or PDF. The LDP way is (again, as
far as I know), to use HTMLDoc to produce PS and PDF from HTML format.
LyX: as I said, I do not think it is a DocBook tool any more than vi is.
Emacs: it also has a DocBook major mode (I think Norman Walsh maintains it).
WordPerfect: again, "recommended for those with money and [...] Windows".
I do not know WordPerfect but what the figure shows and you write about it
Gary, is very similar to what Emacs and sgedit can do.
I do not think it (WP) is "a good reason for having a mult-boot machine".
Writing the HOWTO: I usually like Gary's version, with the following
exceptions:
Demystifying SGML: I do not really understand the purpose of this section.
Who mystified SGML in the first place?
A small wrinkle: I think it should be put into an "Introduction to DocBook"
article.
Writing SGML by hand: "We will say that only ironmen write SGML documents
using only a text editor." Is knowing DocBook a shame?
Revise the HOWTO: is the way you describe not easy?
Well, I got tired by now. I will read the rest tomorrow if nobody tells me
to stop it here...
I hope I was not arrogant. I like many things you suggest Gary and I think
most authors need advice from professional technical writers like you but
the LDP is not OS-neutral. How (and why) would it be?
Cheers,
Pal
Pal Domokos
pal.domokos@usa.net
Mark Komarinski <markk@cgipc.com> wrote:
> I've posted both my latest HOWTO-HOWTO and what I call the alternate-HOWTO
> for lack of a better word. All my comments had to do with footnotes on the
> bottoms of some of the pages. You may want to review both documents, then
> take a look at the comments that got sent to the ldp list.
>
> http://www.cgipc.com/~markk/alternate-howto/
> http://www.cgipc.com/~markk/HOWTO-HOWTO/
>
> -Mark | Mark F. Komarinski, RHCE - Compat. Engineer|
> 176 Second Ave | markk@cgipc.com - www.cgipc.com |
> Waltham, MA 02451 USA | Ph: 781-266-1138 Fx: 781-290-4810 |
>
____________________________________________________________________
Get free email and a permanent address at http://www.netaddress.com/?N=1
--
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org