Re: Authorship

[Gary Preckshot <garrell@inreach.com>]

Thanks for your comments, Pal.

Pal Domokos wrote:

I'd like to deal with one at the end first:

>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?

If anyone could be accused of being arrogant, it's me. See what I wrote at the
end. Meanwhile, be proud of your opinions and don't take a contrary opinion as a
personal insult. It isn't.

>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.

That really never comes through in the HOWTO. Actually, the DTDs, DSSSLs, and
documents are written in SGML, so it's both a metalanguage, and a language whose
syntactical form is used for writing documents. That was the reason I wrote the
section on "Demystifying SGML." You'll notice that the whole section applies to
any document written in any DTD.

>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.

That definitely should be in an appendix.

>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.

That should be in an appendix entitled "Future Directions" since it's just a wish
right now.

>[various link corrections]

I got the links from e-mail on this list, which shows the dire need to get them
right in the HOWTO. I appreciate the corrections.

>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?

One symptom of extreme geekness is assuming that people know how to do things the
author knows how to do or that the system set up the author has is the be-all and
end-all and anybody who doesn't have it is nobody. This section was in there
because HOWTOs are not for people who already know how to, but for people who
don't. Likewise, a lot of people who currently have Windows read the howtos. What
would their preferred operating system be? A geek would say if they're using
Windows they're hopeless, and piss off a potential convert. Lets not make untoward
assumptions. LILO is there for a reason, and some programs on Windows work more
simply and better that those on Linux. It's a sign that Linux programs should be
improved, nothing more.

> ....perhaps Stein's DocBook template would be of greater
help.

I didn't know about it at the time of writing, but if it's a better example, it
should be used.

>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.)

The biggest weakness of the HOWTO-HOWTO, besides being out-of-date when it was
written, is the shotgun approach to listing everything in sight. For instance,
sgmltools is listed and there's nothing that tells you it works mostly with
LinuxDoc. I'm not recommending these tools, but simply saying which work well
together. If you look on Mark's web site, you'll see that his HOWTO leaked some of
the escape sequences into the HTML version. Clearly, some of his tools are
incompatible. We should not eschew tools just because they cost money. If
anything, they're a goad for updating the free tools.

>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.

Provincial. We should list anything that works, with pros and cons. If something
is better than open source tools, then open source tools should look into
upgrading their tools. The FSF isn't about provincialism, it's about sharing the
best information about programming we can find.

Linux is not going to win the battle of the OSs because you or we support it. It's
going to win because it's best and the tools available for it are best. It won't
get best by being provincial.

It already has something Gates doesn't. It reads and writes virtually every
filesystem known to man. Pretty soon, it'll read and write NTFS. Along with LILO,
that makes it a huge threat to Gates.

>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.

vi is an option only if you are into pain.

>Things will definitely change when we move to XML: we will have more tools.

If wishes were horses, then beggars could ride.

>Jade, DSSSL, DocBook 3.1 DTD: RedHat 6.2 and Caldera 2.4 Desktop (probably
most newer distributions as well) contain these packages.

So the HOWTO ought to say this.

>sgmltools: I do not think you actually need this software.

That was my impression. So why is it there?

>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.

This information belongs in the HOWTO. Why isn't it there?

>LyX: as I said, I do not think it is a DocBook tool any more than vi is.

I got that impression.

>Emacs: it also has a DocBook major mode (I think Norman Walsh maintains it).

So we need a lot more detail on emacs. Including screen shots.

>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".

What the figures show is that I got WP working quickly and was able to take
advantage of a lot of DocBook capabilities without much help from the HOWTO-HOWTO.
They also show that the HOWTO was factually wrong when it said that WP had
"limited" support for SGML.

>Writing SGML by hand: "We will say that only ironmen write SGML documents
using only a text editor." Is knowing DocBook a shame?

No. It's stupid. Why learn something a tool can do for you? To show your virtue?
That went out in the middle ages with hair shirts.

>Demystifying SGML: I do not really understand the purpose of this section.
Who mystified SGML in the first place?

You all did. LDP describing SGML is like blind men describing an elephant.

General comments:

Like it or not, the HOWTO-HOWTO is the flagship HOWTO of the LDP. Guylhem asked
why you guys were seen as geeks and how you could attract authors. One of the big
reasons is your HOWTO-HOWTO. Mark did you a service by starting this. Now you have
to realize that it's the primary way that prospective authors see LDP. As such,
it's a defacto statement of LDP policy, and if you can't agree on that, you'll be
seen as a squabbling bunch of primadonnas.

It should have the following qualities:

1) it should be up-to-date. For example, sgmltools are a dead letter. LyX may not
be relevant.

2) it should not be provincial. HOWTOs are the way the non-Linux world gets to be
the Linux world. Tools should not be eschewed just because they are commercial or
they run on a different OS. LILO is there for a reason. A better tool is an
incentive for the FSF.

3) it should be an example of the way you want HOWTOs to be written. It should be
well structured.

4) it should be complete. No small thing should go unexplained or without
explanation by reference.

5) it should not require extreme sacrifice on the part of prospective authors. Vi
sucks as an editor. So does writing SGML by hand. Emacs should be explored. There
may be a reason it's not more popular. Find it.

6) Graphics are modern. Use them.

7) a prospective author, reading the HOWTO-HOWTO, should have all he/she needs to
be a HOWTO author. Nothing should be out-dated, and what the author produces using
these instructions should meet the requirements of LDP. One of the things really
necessary is an example of how to use the DocBook elements. You have so much
freedom with this DTD, that LDP policy is direly needed. You've already had
examples of people asking for guidance. Heed them.

Gary


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org