Re: First pass for LDP-Author-Guide

[Gary Preckshot <garrell@inreach.com>]

Mark Komarinski wrote:
> 
> I'm not going to submit this to the LDP yet, since Jorge and I are
> working on some fine-tuning.  However, I'd like the members to take
> a look at what we're working on and make suggestions before the first
> release.
> I've used db2html to generate the book, so I don't want any formatting
> comments - I'm looking for content comments.
> 

Mark,

A bang-up job! If that's the form it had originally had, I
doubt I would have given you a rewrite. There are some nits
I could pick, but the main thrust, with expanded coverage of
DocBook and screen shots of several editors really gives
useful and relevant information to prospective authors.

One thing you might look over the document and do: get
somebody who's new to try all the links and recommendations.
This is like a final acceptance test for software - you show
that an inexperienced reader can do everything you've put in
the document. His/her comments will be valuable, because
they show you where you were unclear or incomplete. Sorry, I
know too much now, even if you could stomach my comments.

I do have something useful to add on indexing: using
<IndexTerm> seems right, but collateindex.pl seems
unsatisfying. For one thing, your sgml document is
incomplete and becomes customized for one style of output
when you run jade to produce html index information. The
sgml document should be complete with no reference to the
kind of output you're going to get from it. I've found a way
to do this.

1) Use <IndexTerm> as you and Jorge suggest with two
changes: set the id attribute to a unique value (say
"IndexX"). Bookmark the spot so you can return to it.

2) Immediately go to the <Index> and make a new or modify an
old (by adding a <link>) <IndexEntry> in your <Index>. The
index entry will look like this (***...*** is the new part)

<IndexEntry>
  <PrimaryIE>
    <FirstTerm>
      TheWordYouWereIndexing[space]
      <link>1</link>,[space]
      .
      .
      <link>n</link>***,[space}
      <link>n+1</link>***
    </FirstTerm>
  <PrimaryIE>
</IndexEntry>

The new link points back at the <IndexTerm> by using
"IndexX" as the linkend attribute.

3) Return to your bookmark and delete the bookmark.

This method has the advantages 1) that your doc is complete
as it stands, there is no need for post-processing or
customization to a particular output format, 2) the flow of
authoring (if you use a macro) is uninterrupted. You can
index a word (with secondary and tertiary references) as the
mood strikes you.

This sounds fairly involved, but in editors with a macro
capability (like elisp in emacs, and I leave you to come up
with others), you can make the whole process automated and
it takes less than a second. You can do the same for
glossary entries, and lists of figures or tables. References
can be automated to an external database. If it's there, you
use it, and if it's not, you enter it, then use it.

As to what this has to do with DocBook, DocBook makes it
possible by structuring the content as you write so that
macros can be effective.

Gary


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