RE: Authorship

[Gregory Leblanc <GLeblanc@cu-portland.edu>]

> -----Original Message-----
> From: Gary Preckshot [mailto:garrell@inreach.com]
> Sent: Wednesday, May 31, 2000 3:05 PM
> To: LDP
> Subject: Re: Authorship
> 
> Pal Domokos wrote:
> 
[snip]
> 
> >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.

I think that better wording is probably in order.  How about "If your
primary opertaing system is ..."?  

> > ....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 think that it makes a wonderful replacement for example.sgml (Linuxdoc),
and fills a gap in the Docbook resources.

> >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 you don't recomend the ones that are the easiest to use, people might
pick one that's a real pain to work with, get frustrated, and give up.
That's not something we want.  Since we've used a variety of tools, we
should recomend the ones that we found easiest to work with.

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

I have to agree, recomend the best tools that we can.  If a Windows tool is
slight better than a Linux Tool, list the Linux tool first.  If the Windows
tool is a LOT better, list the windows tool first.  From what I've seen,
Emacs has everything that I've heard about in WP, with the added bonus of
being Open Source, and running on Linux.  Again, this may be a holy war for
some, don't make it that.

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

Well, it already reads NTFS pretty darn well.  I've not done any stressful
write testing, but I haven't had any problems with replacing the occasional
DLL that gets screwed up by the latest version of Internet Expoiter.  

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

Religious statement.  VI is a useable editor if you're already familar with
it.

> >Things will definitely change when we move to XML: we will 
> have more tools.
> 
> If wishes were horses, then beggars could ride.

There aren't any XML tools that work right now, so let's not go there just
yet.  

[snip]
> >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?

Probably because Mark wasn't aware of this, or hadn't found time to update
that section of the HOWTO.

[snip]
> >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.

I'll have to see if I can get the Docbook major mode installed.  When Norm
announced the DocBook mode he said something about making it a minor mode of
PSGML, but I know he hasn't had any time to work on it lately.  

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

At the time, it probably did have limited information.  Everybody here is a
volunteer, so sometimes things don't get updated on a very timely manner.
We don't have any facilities in place to do multi-author documents just yet.

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

That's not the case.  The tool cannot give the kind of fine-grained control
that I'd like to have.  The closest that it can come is to let me highlight
some text, and go through some menu that inserts markup around that text.  I
may as well do that by hand.  WP gives better "desk-rodent" support for
inserting tags and figuring out what goes where.  Does it provide for those
of us who only use the "desk-rat" when they're forced to (I don't want
carpel tunnel).

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

SGML is NOT obvious.  I think that's a perfectly appropraite section title.

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

I think that it should give a slight advantage to Linux/Open Source/Free
tools, although if the Free tool is way behind, then that shouldn't make up
for it.  
As a note, the Free Software Foundation (FSF) is not the same as the LDP, or
even as the Open Source community.

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

You're ONLY going to bring flames with that, don't go there.

> So does writing SGML by hand.

Define "writing SGML by hand"?  Do you mean doing something other than just
typing your document into notepad?  The editor can't know when something
you're typing is a command, or the name of an application, so some markup
has to be done by whomever is doing the writing.  I use DocBook to remind me
that such-and-such is something that I type, or is the name of an
application, or whatnot, while I'm writing.

> Emacs 
> should be explored. There
> may be a reason it's not more popular. Find it.

Of course, it's because Emacs is Taboo.  Everybody is afraid that it's hard
to use.  Assuming that you're using some sort of window system (MS Windows/X
window system), then once it's installed, it's NOT that hard to use.
Certainly not any more dificult than MS Word.  People don't use it because
it's something that "the Unix Guru's" use, so it must take YEARS to figure
out, and it can't have any documentation that any normal human being can
understand.  This isn't the case.  I've only been using Emacs for a couple
of months, and it does everything that used to do in a word processor on
windows, and then some.  

> 6) Graphics are modern. Use them.

I agree, but try to provide ASCII diagrams or alternatives where that's
plausible.  I'd hate to get stuck rebuilding my system from a floppy, and
find that my docs had the information that I needed, but it was in a PNG
that I couldn't read.

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

LDP policy is needed, and there are a few examples.  Perhaps if some more
people can go over Stein's Linuxdoc template, and my Docbook version of it,
we can use that as the guideline for DocBook.
	Greg


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