olink element question

[Karen Schneider-2]

I am working on a styleguide and want to clarify naming conventions
for the olink element. I still am struggling to understand this
element so want to make sure that the following is correct (in
reference to a file named filenames.xml):

For simplicity's sake, use the document's xml:id attribute as the
document identifier; it will then function as both the targetdoc and
targetptr element. So the olink reference for this file would be
filenames, as in this example:

See the chapter on <olink targetdoc="lists" targetpr="lists"</olink>

Thanks -- I don't know why I have such a block about the olink element.

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

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...

[Karen Schneider-2]

Urp, correction:

See the chapter on <olink targetdoc="lists" targetpr="lists">creating
lists</olink>

Karen

On Fri, Sep 4, 2009 at 12:35 PM, Karen Schneider<kgschneider@...> wrote:

> I am working on a styleguide and want to clarify naming conventions
> for the olink element. I still am struggling to understand this
> element so want to make sure that the following is correct (in
> reference to a file named filenames.xml):
>
> For simplicity's sake, use the document's xml:id attribute as the
> document identifier; it will then function as both the targetdoc and
> targetptr element. So the olink reference for this file would be
> filenames, as in this example:
>
> See the chapter on <olink targetdoc="lists" targetpr="lists"</olink>
>
> Thanks -- I don't know why I have such a block about the olink element.
>
> --
> --
> | Karen G. Schneider
> | Community Librarian
> | Equinox Software Inc. "The Evergreen Experts"
> | Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
> | kgs@...
> | Web: http://www.esilibrary.com
>

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

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...

[Bob Stayton]

Hi Karen,
If you are going to use an xml:id attribute value for the targetdoc, it
should be that of the top level element in your assembled book.   In your
example, you seem to be referring to a chapter, so I don't think that's
quite right.  The targetdoc value needs to cover all the content of an
assembled book, not just one chapter.  Think of an olink as a two-part
address: the first part (targetdoc) references the book, and the second part
(targetptr) references a point within that book.  Only when you mean to link
to the book element itself would they match.

Bob Stayton
Sagehill Enterprises
bobs@...


----- Original Message -----
From: "Karen Schneider" <kgschneider@...>
To: "docbook-apps" <docbook-apps@...>
Sent: Friday, September 04, 2009 9:37 AM
Subject: [docbook-apps] Re: olink element question

> Urp, correction:
>
> See the chapter on <olink targetdoc="lists" targetpr="lists">creating
> lists</olink>
>
> Karen
>
> On Fri, Sep 4, 2009 at 12:35 PM, Karen Schneider<kgschneider@...>
> wrote:
>> I am working on a styleguide and want to clarify naming conventions
>> for the olink element. I still am struggling to understand this
>> element so want to make sure that the following is correct (in
>> reference to a file named filenames.xml):
>>
>> For simplicity's sake, use the document's xml:id attribute as the
>> document identifier; it will then function as both the targetdoc and
>> targetptr element. So the olink reference for this file would be
>> filenames, as in this example:
>>
>> See the chapter on <olink targetdoc="lists" targetpr="lists"</olink>
>>
>> Thanks -- I don't know why I have such a block about the olink element.
>>
>> --
>> --
>> | Karen G. Schneider
>> | Community Librarian
>> | Equinox Software Inc. "The Evergreen Experts"
>> | Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
>> | kgs@...
>> | Web: http://www.esilibrary.com
>>
>
>
>
> --
> --
> | Karen G. Schneider
> | Community Librarian
> | Equinox Software Inc. "The Evergreen Experts"
> | Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
> | kgs@...
> | Web: http://www.esilibrary.com
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@...
> For additional commands, e-mail: docbook-apps-help@...
>
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...

[Karen Schneider-2]

> ...  The targetdoc value needs to cover all the content of an
> assembled book, not just one chapter.  Think of an olink as a two-part
> address: the first part (targetdoc) references the book, and the second part
> (targetptr) references a point within that book.  Only when you mean to link
> to the book element itself would they match.

Ok, I think I have fought my way through a lot of this block. I'm
writing about a set with two books, each with a number of chapters.

But... I know this question will sound really basic... in reference to
the styleguide itself, versus The Book of Evergreen... as the
styleguide is one book, assembled from chapters, it sounds as if xref
and link will suffice. Maybe I've been thinking too hard this weekend,
but I'm suddenly tripped up by the term "document." Either that, or
understanding it better.

Regarding the set of two books, to prepare the chapters for
cross-referencing, would I start with a document id for the books,

<book id="Book1">
<book id="Book2">

Each one in its respective book, after the XML declaration?

Then in Book 1 we might have a chapter, figures.xml... it too gets a
document id, right?

<chapter id="figures">
<title>Making Purty Figures</title>
<para>yada yada...</para>

Meanwhile, over in the "lists" chapter of Book 2...

<chapter id="lists">
<title>Manly Lists for Handsome Docs</title>
...

<para>However, if you are describing physical items that are
listing--ships, your tipsy spouse, the old shed out back--instead of a
list you may prefer to <olink targetdoc="Book1"
targetptr="figures">use a graphic</olink>.

... Now that I've spelled this out it feels right (and uh, simple). If
I have this correct, it seems that it would also be valuable to
stipulate a convention for document id in the section on file
structure and filename conventions.


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

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...

[Bob Stayton]

Hi Karen,
Yes, the example you provided is correct.

I'm afraid there is some ambiguity in the use of "document", especially when
you divide your content into modular files.  An XML file containing a single
<chapter> element is an XML document, and so is an XML file containing a
<book> element that XIncludes one or more of those chapter documents.  And
outside of XML, "document" typically refers to a published unit.

I think you are calling the id attribute of the root element of each file
the "document id", but that isn't an official XML term.  It just means the
id of the document's root element.

Perhaps "assembly" is a better term for the larger document that is
assembled for release as a unit.   The targetdoc name is are associated with
such an assembly when dealing with modular content.


Bob Stayton
Sagehill Enterprises
bobs@...


----- Original Message -----
From: "Karen Schneider" <kgschneider@...>
To: "Bob Stayton" <bobs@...>
Cc: "docbook-apps" <docbook-apps@...>
Sent: Sunday, September 06, 2009 4:48 AM
Subject: Re: [docbook-apps] Re: olink element question


> ... The targetdoc value needs to cover all the content of an
> assembled book, not just one chapter. Think of an olink as a two-part
> address: the first part (targetdoc) references the book, and the second
> part
> (targetptr) references a point within that book. Only when you mean to
> link
> to the book element itself would they match.

Ok, I think I have fought my way through a lot of this block. I'm
writing about a set with two books, each with a number of chapters.

But... I know this question will sound really basic... in reference to
the styleguide itself, versus The Book of Evergreen... as the
styleguide is one book, assembled from chapters, it sounds as if xref
and link will suffice. Maybe I've been thinking too hard this weekend,
but I'm suddenly tripped up by the term "document." Either that, or
understanding it better.

Regarding the set of two books, to prepare the chapters for
cross-referencing, would I start with a document id for the books,

<book id="Book1">
<book id="Book2">

Each one in its respective book, after the XML declaration?

Then in Book 1 we might have a chapter, figures.xml... it too gets a
document id, right?

<chapter id="figures">
<title>Making Purty Figures</title>
<para>yada yada...</para>

Meanwhile, over in the "lists" chapter of Book 2...

<chapter id="lists">
<title>Manly Lists for Handsome Docs</title>
...

<para>However, if you are describing physical items that are
listing--ships, your tipsy spouse, the old shed out back--instead of a
list you may prefer to <olink targetdoc="Book1"
targetptr="figures">use a graphic</olink>.

... Now that I've spelled this out it feels right (and uh, simple). If
I have this correct, it seems that it would also be valuable to
stipulate a convention for document id in the section on file
structure and filename conventions.


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



---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...

[Karen Schneider-2]

On Sun, Sep 6, 2009 at 8:32 PM, Bob Stayton<bobs@...> wrote:
> Hi Karen,
> Yes, the example you provided is correct.

It's really just the one in your book, rephrased so that I'm
absolutely sure what I'm doing. Which helped!

>
> I'm afraid there is some ambiguity in the use of "document", especially when
> you divide your content into modular files.  An XML file containing a single
> <chapter> element is an XML document, and so is an XML file containing a
> <book> element that XIncludes one or more of those chapter documents.  And
> outside of XML, "document" typically refers to a published unit.

Yes, I can see the ambiguity (it appears to be widespread). I think I
will address that in our glossary -- I have questions about that I'll
gather and post. :-)

>
> I think you are calling the id attribute of the root element of each file
> the "document id", but that isn't an official XML term.  It just means the
> id of the document's root element.

Thanks, this clarification helps.



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

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...

[Karen Schneider-2]

> I think you are calling the id attribute of the root element of each file
> the "document id", but that isn't an official XML term.  It just means the
> id of the document's root element.

Ok -- I'm not as clear on this as I thought.

In the following, can the xml:id function as the document id (without
any additional declaration)? And therefore if this is in a book called
book1 (xml:id book1), can it link to a file called graphics.xml
(xml:id graphics) in book2 (<olink targetdoc="Book2"
targetptr="graphics">use a graphic</olink>?

<?xml version='1.0' encoding='UTF-8'?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="filenames">
  <title>File Structure and Filenames</title>
 ...

>
> Perhaps "assembly" is a better term for the larger document that is
> assembled for release as a unit.   The targetdoc name is are associated with
> such an assembly when dealing with modular content.

That would help disambiguate things... methinks!



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

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...

[Bob Stayton]

Yes, setting xml:id="filenames" in the chapter element is fine.  I'm not
sure what you mean by "without any additional declaration", though.  All
elements in DocBook 5 allow an xml:id attribute, so putting one on the
chapter element does not require any further declaration.  You can put an
xml:id on every element, and link to every element if you like.

Perhaps the phrase "document id" is confusing you here.  Like I said, it is
not an official term, and it is not necessary to refer to an id with it.
When you have <chapter xml:id="filenames">, the xml:id is associated with
the element.  That chapter element could be in its own file, or it could be
included into a book, but the xml:id has the same status: an ID attribute on
an element.   So would it help to just drop the phrase "document id" and
just refer to an id on an element?

Bob Stayton
Sagehill Enterprises
bobs@...


----- Original Message -----
From: "Karen Schneider" <kgschneider@...>
To: "Bob Stayton" <bobs@...>
Cc: "docbook-apps" <docbook-apps@...>
Sent: Monday, September 07, 2009 9:33 AM
Subject: Re: [docbook-apps] Re: olink element question


> I think you are calling the id attribute of the root element of each file
> the "document id", but that isn't an official XML term. It just means the
> id of the document's root element.

Ok -- I'm not as clear on this as I thought.

In the following, can the xml:id function as the document id (without
any additional declaration)? And therefore if this is in a book called
book1 (xml:id book1), can it link to a file called graphics.xml
(xml:id graphics) in book2 (<olink targetdoc="Book2"
targetptr="graphics">use a graphic</olink>?

<?xml version='1.0' encoding='UTF-8'?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="filenames">
  <title>File Structure and Filenames</title>
 ...

>
> Perhaps "assembly" is a better term for the larger document that is
> assembled for release as a unit. The targetdoc name is are associated with
> such an assembly when dealing with modular content.

That would help disambiguate things... methinks!



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



---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@...
For additional commands, e-mail: docbook-apps-help@...