Re: [docbook-apps] Creating a DocBook glossary in a distributed documentation production environment

[Karen Schneider <kgschneider@gmail.com>]

Dick, this would at least be a good start (for the glossary). I had
looked at 17 but was still mulling process and workflow. What you
write makes sense. On the Subversion repository we're going to do
something very similar to that. I like the gloss.term idea, and a
public repository, which we are already using, gives the authors an
easy place to look to see if a term has already been added.

From previous editorial experience, I will state in the guide that
there will be one entry per term. Editors will break ties, enrich
definitions, etc. Any other way lies madness ;-)

Karen

On Mon, Sep 7, 2009 at 5:57 PM, Dick Hamilton<rlhamilton@frii.com> wrote:
> Karen,
>
> For a simple distributed DocBook production environment, I'd
> suggest a Subversion repository that all authors use for their
> individual parts, as well as shared parts (like the glossary).
>
> I'd use a glossary database (Chapter 17 of Bob's book) that is
> writable by any author. Authors can populate it with whatever
> terms they like, using a simple rule for id disambiguation (I
> use gloss.term, where gloss is constant and term is the term
> itself. If you need to disambiguate two forms of the same term,
> you can add something at the end.)
>
> If two authors need to use the same term, they will need to
> discuss whether they can create one entry for both uses, or
> if they need separate entries, but beyond that, there's not
> much need for coordination.
>
> The build process described in Bob's book buildsa glossary for
> each document based on the terms used in that document. Simple
> and automated.
>
> Hope that helps.
> Dick Hamilton
> ---------------------------------
> XML Press
> XML for Technical Communicators
> http://xmlpress.net
> (970) 231-3624
>
>
>> -----Original Message-----
>> From: Karen Schneider [mailto:kgschneider@gmail.com]
>> Sent: Monday, September 07, 2009 12:11 PM
>> To: docbook-apps
>> Subject: [docbook-apps] Creating a DocBook glossary in a
>> distributed documentation production environment
>>
>>
>> This is half a DocBook question and half a "process" question for
>> anyone on this list working in a distributed DocBook production
>> environment where for a particular assembled document you are
>> generating at least one common glossary. (In this case, the assembled
>> document is planned as a set with two books, multiple chapters within
>> each book, and sections within each chapter.) Authors will be working
>> on chapters and sections independently of one another.
>>
>> I am trying to figure out the logistics of having authors generate
>> glossterms/glossentries that are unique and consistently-formed and
>> contribute to a common glossary. It may well be that this isn't
>> possible, or that it is best done as a sort of kludge, where they mark
>> up glossterms and then submit the full glossary entries in a separate
>> document, for editors to manually integrate this content into a main
>> glossary after human review. Either that, or authors ignore glossary
>> creation altogether and the next tier of editors is responsible for
>> glossary creation.
>>
>> I have read through the instructions for glossary databases in
>> Stayton's guide, thought about manual vs. automated creation, etc. but
>> am still stuck at the "process" level of all this.
>>
>> --
>> --
>> | Karen G. Schneider
>> | Community Librarian
>> | Equinox Software Inc. "The Evergreen Experts"
>> | Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
>> | kgs@esilibrary.com
>> | Web: http://www.esilibrary.com
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
>> For additional commands, e-mail:
>> docbook-apps-help@lists.oasis-open.org
>>
>>
>
>
>



-- 
-- 
| Karen G. Schneider
| Community Librarian
| Equinox Software Inc. "The Evergreen Experts"
| Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
| kgs@esilibrary.com
| Web: http://www.esilibrary.com