[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Book title in bookmap
Hi,
Yes, I guess I tend toward option four. I also question the other
examples you give. Generally, I don't like text in book files, but I
also don't understand some of them.
I don't understand what text would go between topics. Is it chapter
grouping text, like "This chapter is about..." or is it actually between
sections of an eventual chapter? I'd need to see an example of this to
tell for sure, but it seems to me that would be one more topic
referenced in the book, either as a parent of the section topics or a
sibling between them.
I also have a question on book specific index markers. Does that mean
there is one case where you would want readers to find content and one
where you wouldn't? I don't see why you would not include index entries
that are related to content that is included. Are the other locations
other books, or other deliverables?
Copyright statements, along with front matter kinds of things like
conventions pages, regulatory statements, compliance statements, safety
statements, target audience, disclaimers, etc. seem like the perfect
thing to share between lots of books. When I think of boilerplate text I
don't plan to paste it into every document I publish. Should boilerplate
text get updated, I don't want to track corrections through all of the
places it's been published. I'd rather go to one file and fix it.
I don't have a counter for the special index title example, but I also
can't really see it. Editorial choices aren't generally arbitrary. Can
you provide a concrete example? Also, it occurs to me that there
shouldn't a consideration for one book. There may be a situation like
the one you describe, but it would be over a class of books. Only in the
case of failure does a single project not convert to a program. This
relates to the other examples as well. Is it efficient to make the same
changes in a number of books as the program expands?
The index example led me to another part of the book map, and I have
another question. In the booklists description, the following sentence
appears. "The placement and order of the lists in the resulting book is
determined not by location in the bookmap but by an external style
preference setting (whether the list of figures comes before the list of
tables, for example)." How does that setting work? Is it a parameter
list of some kind?
Thanks,
Kevin
-----Original Message-----
From: Robert D Anderson [mailto:robander@us.ibm.com]
Sent: Wednesday, April 05, 2006 10:03 AM
To: Farwell, Kevin
Cc: dita@lists.oasis-open.org
Subject: RE: [dita] Book title in bookmap
Hi Kevin - just to clarify, option 1 would still leave the title in the
map. It would just force us to come up with a specialization that fits
it into the bookmeta element (bookmeta is specialized from topicmeta). I
think this would be an awkward fit, especially given that we already
plan to put the title element into maps for DITA 1.2. So I think you are
proposing a fourth option - do not allow the user to set a title in the
map?
On a broader note - I can see many places that the map will contain
translatable text. Offhand, several are:
- Transition text between topics. This is text that's only appropriate
in the book, to help the content flow from one topic to another. If this
text goes into the topics, the topics are not easily reusable outside of
the book.
- Index terms that are useful in this book, but are not useful when the
topic is reused in other locations
- Copyright statements
- Alternate titles for generated sections: if users include an
<indexlist>, they will get an index in the output. It most
implementations this will get a default heading of Index. If the user
needs to change the heading for one book, they can and should do so by
giving an alternate in the map (through the navtitle attribute, or
through the navtitle element after DITA 1.2).
This is also useful when specializing to create a new type of index
(Part Number Index, Index of APIs, etc).
Like the book title, these are all specific to the book, so I am not
sure why we would try to keep them out of the bookmap. If we put all of
this in another file, the same things would be true of that file (one
more item to manage, version, and translate).
Thanks-
Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit
(507) 253-8787, T/L 553-8787
"Farwell, Kevin"
<Kevin.Farwell@li
onbridge.com>
To
Robert D
04/05/2006 10:35 Anderson/Rochester/IBM@IBMUS,
AM <dita@lists.oasis-open.org>
cc
Subject
RE: [dita] Book title in bookmap
Hello,
I'd vote for option 1. I'm not in favor of having any translatable
content in the book map. That just makes one more file to translate, one
more place to manage terminology, one more file to version, and one more
place mistakes can be made. If the book file is only a collection of
references to external content, the efficiency of the map is preserved.
The conflict is unavoidable. People using book maps now, with their
titles in attributes, will have to rework their files either way.
Kevin
-----Original Message-----
From: Robert D Anderson [mailto:robander@us.ibm.com]
Sent: Monday, April 03, 2006 2:09 PM
To: dita@lists.oasis-open.org
Subject: [dita] Book title in bookmap
Don and I were working on the bookmap DTD, and ran in to a problem. When
we originally put the proposal together, we were planning for one large
release rather than the current 1.1 and 1.2 releases. As part of the
design, we counted on proposed feature number 11, which had already been
approved:
http://www.oasis-open.org/committees/download.php/13734/IssueNumber11.ht
ml
This is the proposal to make translatable attributes into elements. One
of the items in that proposal is to add a <title> element to map, to be
used instead of the title attribute. The book model really needs this
title element in order to allow for more structured book titles, such as
title + library information. Unfortunately, feature #11 was moved to
1.2, so it will not be released with bookmap. I see three possibilities:
1. We force the title into the bookmeta element. This could work, but
will cause conflicts with the title element once 1.2 is released (and
bookmap is updated for the change).
2. We do that one part of #11 in 1.1 -- we just allow the title element
inside map. Leave the others for 1.2.
3. We let the 1.1 scope creep to include all of #11
I would vote for #2 - the partial implementation that brings the title
element into maps. Any other thoughts?
Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit
(507) 253-8787, T/L 553-8787
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]