Re: First pass for LDP-Author-Guide

[Mark Komarinski <markk@cgipc.com>]

jdd wrote:
> 
> I'm just reading your work. First I think this work must be done and that
> you make a very valuable effort. Don't take any remark for a flame. I'm
> not fluent in english but want only to help.

Got it.

> I use linuxdoc now for 2 years and never manage to make docbook run nicely
> on my PC (may be soon done!).
> 
> SGML is not XML
> 
> this paragraph is for me a perfect nonsense (it doesn't mean anything). I
> heard about XML for now more than one year and never understand exactly
> what it is :-)
>
> some time I see it as a data base format, sometimes as a document one.
> Only sure it is text and tags. what else?

Sounds like XML alright.  My impression (someone correct me when I go astray)
is that XML can store binary data within tags, while SGML cannot.  This
makes XML much better for things like storing pictures, encrypted data, etc.
Rumor is that MS Word's XML support is just putting their proprietary data
in XML tags, which doesn't help anyone at all.

The SGML paragraph was rather hastily added after the discussion from
yesterday.
 
> "A catalogue is a text file containing the translation rules of the
> public identifier to system's files."
> 
> this (chap 5, creating and modifying catalog) is a perfect example of what
> should not be done. what is the public identifier?

Jorge's first language isn't Engligh either.  I don't want to modify too
much of his stuff to make it sound better (yet) until I get an okay from
him.

> please fine tune the words and langage. HOWTO users are frequently not data
> processing aware
> 
> what I mean is that trying to explain a difficult word by a more difficult
> one is bad.  say, f.e.
> a catalog is a text file. (this I understand : I can read it with vi)
> In that file are translation rules, that is explainations of how the tags
> of the source file will be uses to make paragraphs or titles # is it
> right?
> I still don't know what is the public identifier to system file ?
> 
> if, after reading the few example, the pretending author always prentends
> to use docbook, he's VERY courageous...
> 
> For New Authors
> 
> this paragraph is very confusing. It seems to say that  "you may write
> your documentation in the format of your choice"
> 
> and
> 
> "another LDP volunteer will translate your document into DocBook"
> 
> I don't think this is the "normal" subscription method. anyway I will
> probably very difficult to to this txt to docbook translation (if not, why
> discuss about docbook!)

Ask the powers-that-be.  We're hashing this discussion around in another thread
(or is that one done?).  The idea is that if an author doesn't know DocBook, they
can write it in .txt, send it to the LDP, get it translated into DB, then use
the LAG to maintain the document.

> jade & co
> 
> this paragraph is horrible.
> 
> think as you where a very beginner (as of docbook, of course). how can you
> make a choice between jade and openjade?

I can't.  Some applications require the use of jade (i.e. autoconf looks
specifically for jade, others look for both).

> we absolutely need a ONE SOURCE rpm (or tgz) that install all this stuff
> in one step.

No no no!  Then we're getting into software maintenance and that would
only increase the existing overhead.  RPM-based distros have the Cygnus
DocBook tools, which includes Jade, the DSSSL, and DB 3.1.  I already
documented this, and also document the "do it by hand" method after installing
all the tools separately.

> "this is the successor to the sgmltools projec"
> 
> what is the interest of saying this ? oldtimers knows this already and
> beginners don't have to.

I still document sgmltools (for some reason).

> I think it would be a VERY goog idea to write an LDP-history-guide (on the
> Internet all is too soon forgotten), but not here.
> 
> please, choose betxeen cygnus and sgml_lite, how can I do that ? or at a
> minimum say: beginners, do that, others lurk by that

Cygnus is easy install for RPM-based distros.

> I stop reading this and download the recommended book (but still in
> english, I know many people that dont like hundred page's english books.

That's why I bought it, and I'm sure that's why ORA and Norman decided
to release the source.

> just a word : what about non english writers? you propose help for
> translating from txt to docbook, what about translating from - says -
> french to english? may be valuables authors don't speak english...

Uhm...can I get a ruling from higher-ups?

-Mark

-- 
--------------------------------------------------------------------
Carlo Gavazzi IPC     | 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         |


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