Re: [docbook-apps] Please respond: adding generic sibling to high-levelbook components

[=?ISO-8859-15?Q?Camille_B=E9gnis?= <camille@neodoc.biz>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Camille internal thoughts:

- - "Hey that's just a documentation issue! and we are good at making
documentation, it's just a matter of a semantic index that would point
the user to a tag/attribute pair corresponding to his need."

- - "But we all know users don't read documentation :-) They rely on the
list of choices the editor tool will propose them."

- - "Yes, but will they scan all 1000 inline elements proposed?"

- - "Well that's little difference to scanning documentation."

Oh well...

Camille.

Michael(tm) Smith a écrit :
> Peter Ring <PRI@magnus.dk>, 2007-02-23 10:23 +0100:
> 
>> Camille Bégnis wrote:
>>> Rationale: When our clients come to docbook they are frightened by the
>>> number of elements. So we provide them with a limited list so they can
>>> get started. But while they start learning new elements they realize
>>> they should have called that element <preface> rather than <chapter>.
>>> And it's easier to add an attribute to specialize the element rather
>>> than renaming it, possibly with content model issues.
>>>
>> I'd second that, i.e., favor generic elements that can be
>> specialized by adding child nodes (attributes and elements) --
>> without changing the element name.
>>
>> I also happen to like <systemitem>. A <systemitem
>> class="library"> is 'a kind of' or 'an extension of'
>> <systemitem>;
> 
> And what exactly is a systemitem? Where, outside of the DocBook
> community, is the term "system item" familiar to anybody, or where
> does it have any kind of documented meaning?
> 
> It seems to me that systemitem@library simply forces users to
> consider a library as a "kind of" or "extension of" a class of
> things that are not necessarily intuitively related to each other
> at all -- the class that we're using the invented name
> "systemitem" for.
> 
> How are we expecting users to discover that we have classified a
> library as a class of a "system item"?
> 
> For the situation where we have a new user who wants to mark up,
> say, both a constant and a username or a constant and and IP
> address, we are expecting the user to do ... what. Say to himself,
> OK, those are both classes of things that are used on a system, so
> I guess I should maybe I should find an element that starts with
> the name "system"?
> 
> How likely is it that a user is going to do that, as opposed to
> doing the intuitive thing of looking for an element called
> Username or Contast or IPAddress?
> 
>> the proliferation of @class values is just a reflection of the
>> number of system-related terms that have similar behavior.
> 
> No, it's simply a reflection of that fact that we have chosen to
> classify all 22 of those things as "system-related terms"
> (whatever that means). And how the behavior of a constant similar
> to the behavior of a library or a username>
> 
>> To the extent that a number of elements have similar content
>> models and similar processing expectations, it is a moot point
>> whether you say <gi class="special">...</gi> or
>> <gi><special/>...</gi> or <special>...</special>, cf. "Should I
>> use elements or attributes to store data?" [1].
> 
> No, it's not very far from being a moot point. At least not to
> users. Users who wants to mark up a certain piece of information
> intuitively go looking for an element name that matches the name
> of the type of information they want to mark up. They do not go
> looking for an element with the name: [insert invented element
> name with with you've chosen to classify a set of things that
> users may or may not consider to be similar or related].
> 
> The big difference is that with the @class approach, you are
> forcing your classification scheme on users, and requiring them to
> learn and adopt it in order to mark up their content. By providing
> elements instead, your not forcing any particular classfication
> scheme on users, and they choice of how they want to consider
> semantic relationships among the elements is instead left up to them.
> 
>   --Mike
> 

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (GNU/Linux)
Comment: Using GnuPG with Mandriva - http://enigmail.mozdev.org

iD8DBQFF3sJkjv9P65BfOUMRAqucAKCZhKKSOuitsB42VuS4TmF8pZ2ZogCdE1XH
32K+mxuz08j1keQ2dOvmqY4=
=6R+J
-----END PGP SIGNATURE-----