RE: [docbook-tc] Opening discussion of the Assembly schema

["Rowland, Larry" <larry.rowland@hp.com>]

1) Description is what the original attribute was called, but there was
some objection to it (I don't remember exactly what).  That's what it
is, and a manifest is probably not the only possible destination for
the content.  I would be happy to go back to calling it a description.
I think alt is stretching a bit.

2) Someone suggested allowing namespaces, but I don't remember the
context.  It was quite a while ago.  I would suspect they are from
the tool environment rather than from the author -- if the tool
chain does not recognize them, they would serve no real purpose.

-----Original Message-----
From: Norman Walsh [mailto:ndw@nwalsh.com] 
Sent: Wednesday, May 11, 2011 10:54 AM
To: docbook-tc@lists.oasis-open.org
Subject: Re: [docbook-tc] Opening discussion of the Assembly schema

"Rowland, Larry" <larry.rowland@hp.com> writes:
> As requested at the last TC meeting, I am initiating a discussion of
> how well the current schema at top of tree reflects the recent 
> discussions of the assembly at TC meetings.
[...]
> 1) The element "manifesttext" is missing.  It is intended to provide
>    descriptions of the resources for a manifest document generated by
>    parsing an assembly that has a set of resources designed to be
>    reused across assemblies, to support easy reuse of shared
>    resources.  It replaces a proposed description attribute that was
>    rejected due to localization concerns about putting editable text
>    in an attribute.  It is intended for simple (typically a sentence
>    or phrase) descriptions, so little, if any, markup should be
>    allowed inside it.  I assumed CDATA.  
>    A) The element "manifesttext" should be allowed as a child of
>       "resources."
>    B) The element "manifesttext" should be allowed as a child of
>       "resource."

Can we overload "alt" for this purpose? I'm not sure that's a good idea,
I'm just wondering out loud. If not, I think I'd prefer an element
called "description" or something more generic than "manifesttext".

> 2) The attribute "format" on the "output" element originally allowed
>    multiple tokens rather than a single one.  This was to allow a
>    single output element to bind a characteristic to multiple output
>    formats (such as webhelp and ohj, which frequently have similar
>    delivery structures).  If it does not allow multiple tokens, the
>    same result can be achieved by repeated binding of the
>    characteristic to multiple output statements, but the intent may be
>    less obvious.
>
>    Allowing the tokens to include name spaces was also discussed,
>    supporting something like "dita:webhelp" to indicate the output is
>    in the form of a webhelp system described by DITA as opposed to
>    "db:webhelp" which would specify a DocBook Webhelp system.

Multiple tokens is ok by me. I'm agnostic on whether they should have
namespaces or not. On the one hand, it would distinguish between
dita:webhelp and db:webhelp, but aren't the tokens just invented by
the author? Are we really expecting assemblies to be reused and shared
in ways that require namespaces?

> 3) It may be desirable to allow the element output in more positions
>    as a child of structure, it currently has to precede title, which
>    was somewhat confusing, as I initially concluded it was not allowed
>    as a direct child of structure.  I had title and titleabbrev
>    preceding the output elements in one file, but following it in
>    another or I would have concluded it was not allowed as a child of
>    structure based on a single instance that had it in the wrong
>    position.  Similar concerns apply to positioning it inside a
>    module.

Hmm. As long as it doesn't torture the content model, I've no
objection to allowing it in more places.

> 4) The attribute "chunk" should be allowed on the element "output," as
>    well as on "module," to deal with situations where chunking needs
>    to be specified for one output but not for others into which the
>    same structure is being rendered.  If specified on a module as well
>    as on an output element that is a child of the module, the value of
>    the attribute on the module is the default for all outputs and the
>    value on the output element overrides the default for the specified
>    outputs.

Ok.

> 5) The attribute "linking" needs to be added to the element "instance"
>    to allow specifying the type of linking.  Example values include
>    "targetonly" and "destinationonly," and "pathshome," and
>    "listdestination."  This is the name of the attribute used for much
>    the same purpose in DITA.

Ok.

> 6) The attribute "type" should be allowed on the element
>    "relationships" to allow defining groups of relations with specific
>    characteristics based on the type specification.  Example values
>    include "pathlist" and "lists."

Ok.

> 7) The element "instance" needs to be added as a child of
>    "relationships" to support the use of relationships to describe
>    combinations of paths through documentation.

Ok.

I've struggled from the very beginning to keep things simple. I'm just
operating on faith that we really need all these knobs. As I go
through the exercise of writing down the semantics and trying to
implement them, I may want to push back a bit, but for the moment I
don't want to be standing in the way.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Convictions are more dangerous
http://www.oasis-open.org/docbook/ | enemies of truth than lies.--
Chair, DocBook Technical Committee | Nietzsche