Re: [docbook-tc] assembly metadata

[Norman Walsh <ndw@nwalsh.com>]

"Bob Stayton" <bobs@sagehill.net> writes:
> I'm following up on my action item to initiate a discussion of
> metadata in assembly. Here are the minutes from the last meeting:
>
> --------------------------------------------------------------
> Scott raised the issue of adding info to module and other
> assembly elements to support metadata.  Norm had
> added info in order to hold a title that would override
> the title in the resource it pointed to.

More specifically, override any info metadata in the resource it
pointed to.

> Bob objected
> to using info for override content as well as
> metadata for assembly elements.  It was agreed that
> they need to be differentiated.
> ----------------------------------------------------------------
>
> I'll start the discussion by suggesting that we add an info element,
> but document it as holding information to describe the current
> assembly-level element, not the element pointed to. I would also
> suggest adding another element, perhaps named <override>, whose
> purpose is to contain content that is to override the content of the
> element pointed to. So if you want a new title to replace the title
> in a topic, you would put that title into a module's override
> element.

My experience with make files, ant build scripts, XProc pipelines and
the like suggests that it will be relatively uncommon for authors to
properly document assembly files and exceptionally rare for them to
need info content.

I would prefer to use <info> in the assembly as providing alternate
info for the included content. But if we really need to support an
info-style wrapper for assembly content, I suppose that's going to be
confusing.

> Here some suggestions for discussion:
>
> 1. Permit <info> on any element in an assembly.
>
> 2. Define the content of info like the DocBook 5 info element.
>
> 3. An info element in <structure> can contribute to the output, just
> like the info element on the root element of a document.
>
> 4. An info element in any other assembly element generally does not
> contribute to the output, although I'm sure there are cases where it
> could.

Let's try to put a stake in the ground: it does or it doesn't. I vote
"doesn't".

> 5. Permit <override> only on <module>.

I don't think that works. It's sometimes going to be useful to change
the title at the module level when it's being loaded into a structure.

> 6. Define the content of <override> to be only those elements that
> make sense to be overridden. Not sure what that list is, though.

Let's not. Let's assume authors know what they're doing.

> 7. Any element in <override> is merged with the content that the
> module points to, and overrides it if the corresponding element
> exists in the resource.
>
> I don't much like the name <override>, so I'm open to suggestions.

Yeah. If we use "override" now to mean "override-info" then when we want
to override something else later, we're stuck. So I guess override-info
is one option. Or make it override:info using some other namespace URI.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | We cannot put off living until we
http://www.oasis-open.org/docbook/ | are ready. The most salient
Chair, DocBook Technical Committee | characteristic of life is its
                                   | coerciveness: it is always urgent,
                                   | 'here and now' without any
                                   | possible postponement. Life is
                                   | fired at us point blank.--José
                                   | Ortega Y Gasset

PGP signature