Re: Authorship

[Mark Komarinski <markk@cgipc.com>]

Joe Cooper wrote:
> 
> Gary Preckshot wrote:
> >
> > Mark Komarinski wrote:
> >

Uhm..I didn't write any of this.  Wrong attribution lines?

> > Mark, you're getting some good feedback from new authors. David Merrill, Joe
> > Cooper, and Arnault Claden just told you that they're having real problems
> > getting the tools working. These are not old hands, but new authors whose
> > feedback is invaluable in determining how useful your howto is to the intended
> > audience. I'm just the most vocal of the set.
> 
> Careful, Gary, not to speak too boldly in the name of other folks.
> 
> I agree that the DocBook tools need better documentation.  But I'm not
> of the opinion that we need better authoring tools.  vi looks great to
> me with the lovely syntax highlighting.  Fast, familiar, and easy.
> 
> All I want from the HOWTO-HOWTO is this:
> 
> 1. Get the DocBook stuff here.
> 2. Install it this way.

Some of this depends on what distro you're using, and what tools you want to
use.  So far I've documented sgmltools on Red Hat and Debian, and Cygnus tools
on RedHat, and the do-it-yourself method which should work on any distro, or
probably any *IX.

> 3. Put this DTD here and do this to make it available.

My latest rev is documenting this.

> 4. Here's an example of DocBook SGML.  Here's a template, too.

This is being worked on outside what I'm doing.  There are SGML templates that
I'll probably link to.

> 5. Type this command to convert your SGML file into these formats.

Also being worked on.  But also depends on what tools you use.

> 6. Send the SGML file here so it can be included in the LDP.

Already done.

> 7. Thank you for helping the LDP.

Ooh. Didn't think of that.

> 
> I think Mark has very nearly covered that just fine in only one of the
> chapters.  It's still a little rough...but getting better.  The
> reference to Godoy's DocBook HOWTO maybe a problem...since that HOWTO is
> confusing, to me anyway.

I'm one for practical examples, and I'm starting to include some tips
and tricks based off what I've run into (using mediaobject instead of
graphic, for example).  Hopefully, the H-H will be a good SGML example.

> > 2) It defuses the responsibility for a coherent policy to several squabbling
> > authors.
> 
> The LDP _is_ a bunch of squabbling authors.  No need for it to stop
> being that.  But the basics ought to be made clear, and respected by
> all.  The basics, in my mind, being:
> 
> - DocBook SGML == Good || LinuxDoc SGML == Ok, but not forever
> - Use your favorite text editor, here's a template that we think
> represents the right style for LDP docs
> - Don't invent your own system of grammar
> - Don't try to push your own political/social/computer/business ends via
> the LDP
> - Be sure to listen to comments from readers and take them to heart the
> next time you are revising your document

Hee.  Good ideas.

> The notion of catering to Windows users or converting Windows users to
> Linux doesn't really seem a worthy goal.  Yes, I consulted the HOWTO's
> like a bible when I was switching to Linux 2 years ago.  But I don't
> believe the job of the LDP is to convert people, or to make it easy for
> Windows users to clutter up the LDP with irrelevent or ill-informed
> HOWTO's.

I think listing tools that work and are affordable is a good thing, no matter
the OS.  I've corrected my WordPerfect comments because a reader has
reported success with it.  Who am I as a Linux advocate and HOWTO author
to tell an author they must use Linux-only tools?  I think it's fair to say
that we have a strong preference towards Linux tools, but if they work
and can be documented, why not list it?

-Mark


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