OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-tc message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

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.


> 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.


> 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."


> 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.


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,

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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]