On Sat, 2004-08-14 at 11:56, Dave Pawson wrote:
> On Fri, 2004-08-13 at 19:13, Karsten Wade wrote:
> > Since this is all FDL covered materials, we do our own licensing choice
> > a service by making it easier to use our works in a truly free manner.
> >
> > I'd recommend a standard of:
> >
> > <section id="like-the-title">
> > <title>Like The Title: The Details</title>
> >
> > The ID has meaning to the content.
>
> the (nominal) typo there immediately hints at a weakness in
> doing this manually?
I intentionally gave the ID a shorter version of the title. The way I
wrote it was confusing, I should have written:
<section id="like-the-title">
<title>The Title That Is Longer</title>
>
> > When moving chunks if <section>s
> > around, you can know what something is easily. Want an idea what
> > sections you have in what order? 'grep "<section" *.xml' gives back
> > something meaningful that directly corresponds to your table of
> > contents.
> If the content is sufficient to warrant that then the complexity
> will make it nominally difficult to re-use in alternate order?
Not at all. Even a short <article> can benefit from this. Since not
all of the <sections> are revealed in our table of contents (by choice),
this is the best way to see every <section>.[1]
While writing, I will move and combine sections all the time, especially
on a larger work. The initial outline represents about 60% of what I
expect to see in the final. This is just my style, but I'm not unique
in this style. To me, outline == guideline.
FWIW, without ID attributes, it's still possible to gain mainly the same
meaning[2]:
grep -A1 "<section" *.xml | grep "<title"
I find it helpful to be able to draw that information (kind of an
instant ToC) at any time, without having to build to HTML or fix the
XSL. :)
>
>
> > Any other thoughts on this? I'll hold off for a bit on filling out the
> > bug report. :)
>
> I wouldn't mandate either. There will be occasions when nested depths
> will be wanted.
Can you give some examples? If <sections> are automatically nested,
what value is there in having fixed <sectn>? Especially if the practice
is deprecated?
- Karsten
[1]
This is what grepping for "<sect" in a single chapter gets me in one of
my books:
<sect1 id="s1-services-ttr-categorization">
<sect2 id="s1-services-ttr-cat-overview">
<sect2 id="s2-services-ttr-cat-classes">
<sect1 id="s1-services-ttr-cat-scenarios">
<sect2 id="s2-services-ttr-cat-new-category">
<sect2 id="s2-services-ttr-cat-del-category">
<sect2 id="s2-services-ttr-cat-new-parents">
<sect2 id="s2-services-ttr-cat-removing-parents">
<sect2 id="s2-services-ttr-cat-retrieving-subcats">
<sect2 id="s2-services-ttr-cat-retrieving-objs">
<sect1 id="s1-services-ttr-notification">
<sect2 id="s2-services-ttr-notif-simple">
<sect2 id="s2-services-ttr-notif-attachment">
<sect2 id="s2-services-ttr-notif-digest">
<sect2 id="s2-services-ttr-notif-email">
<sect1 id="s1-services-ttr-workflow">
<sect2 id="s2-services-ttr-workflow-simple">
<sect2 id="s2-services-ttr-workflow-task-add">
<sect2 id="s2-services-ttr-workflow-task-rollback">
<sect2 id="s2-services-ttr-workflow-task-finished">
<sect1 id="s1-services-ttr-versioning">
<sect2 id="s2-services-ttr-versioning-dataobj-level">
<sect2 id="s2-services-ttr-versioning-fully-versioned">
<sect2 id="s2-services-ttr-versioning-recoverable-types">
<sect2 id="s2-services-ttr-versioning-api">
<sect2 id="s2-services-ttr-versioning-pdl-syntax">
<sect2 id="s2-services-ttr-versioning-old-vs-new">
<sect1 id="s1-services-ttr-search">
<sect2 id="s2-svces-ttr-searchable-object">
<sect3 id="s3-svces-ttr-search-searchable-core">
<sect3 id="s3-svcs-ttr-searchable-supl">
<sect3 id="s3-svces-ttr-searchable-content">
<sect3 id="s3-svces-ttr-searchable-reg">
<sect2 id="s2-svces-ttr-search-ui">
<sect3 id="s3-svces-ttr-search-ui-basic">
<sect3 id="s3-svces-ttr-search-ui-results">
<sect3 id="s3-svces-ttr-search-ui-filter">
<sect3 id="s3-svces-ttr-search-ui-note">
<sect2 id="s2-svces-ttr-search-engine">
<sect2 id="s2-svces-ttr-search-indexer">
[2]
Here's the same file, grepping for "<title", which has more contextual
meaning:
<title>Categorization Tutorial</title>
<title>Overview</title>
<title>Classes</title>
<title>Categorization Scenarios</title>
<title>Creating a new Category</title>
<title>Deleting a Category</title>
<title>Adding more Parent Categories</title>
<title>Removing Parent Categories</title>
<title>Retrieving all Subcategories of a given Category</title>
<title>Retrieving all child objects of a given Category</title>
<title>Notification Tutorial</title>
<title>Creating a Simple Notification</title>
<title>Creating a Simple Notification with an Attachment</title>
<title>Creating an Hourly Digest</title>
<title>Email Alerts</title>
<title>Workflow Tutorial</title>
<title>Simple Workflow</title>
<title>Adding a Task to a Workflow </title>
<title>Rolling Back a Task</title>
<title>Completing a Task</title>
<title>Versioning Tutorial</title>
<title>Data-Object-Level Service</title>
<title>Fully versioned types</title>
<title>Recoverable types</title>
<title>Versioning service API</title>
<title>PDL Syntax</title>
<title>Differences between &WAFX; 5.2 and 6.0</title>
<title>Search Tutorial</title>
<title>Making a domain object searchable</title>
<title>Core search metadata</title>
<title>Supplementary search metadata</title>
<title>Content provision</title>
<title>Metadata provider registration</title>
<title>Creating a search user interface</title>
<title>Basic search form</title>
<title>Displaying results</title>
<title>Filtering results</title>
<title>Note search component</title>
<title>Providing a new Query engine</title>
<title>Providing a new Search indexer</title>
--
Karsten Wade, RHCE, Tech Writer
a lemon is just a melon in disguise
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
