<section> vs <sect1>, ... [was: Re: usb-keys]

[Karsten Wade]

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