Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

#198 add person element

v5.0
closed-fixed
Norman Walsh
5
2006-06-02
2006-04-11
Scott Hudson
No

I think it would benefit the community to create a new
"person" element with a class attribute (to include
author, editor, copyeditor, graphicdesigner, other,
productioneditor, technicaleditor, translator) that
provides a more generally applicable usage than the
current author, editor and othercredit elements.

This would be useful in many scenarios when you need to
describe a person or role that is not as obscure as
"othercredit".

Possible applications could include generating employee
directories, describing roles of individuals required
in certain procedures (factory assembly, real-time
procedures such as launch or activity), etc.

For DocBook 5.0, I'd like to see author, editor and
othercredit deprecated in favor of the more general
person element.

Discussion

  • Norman Walsh
    Norman Walsh
    2006-04-12

    Logged In: YES
    user_id=81663

    I think DocBook 5 has this right already: author, editor,
    etc. include either orgname or personname. That allows for
    documents authored by organizations which isn't that uncommon.

    We could create new elements: copyeditor, graphicdesigner,
    translator, produtioneditor, etc. but why is that superior
    to othercredit role="copyeditor" or the like? I guess a
    class attribute on othercredit would at least give an
    enumerated list.

    And I'm sure we both see that your examples: employee
    directories, factory assembly, real-time procedures in a
    rocket launch, etc. are not all strictly in scope.

     
  • Scott Hudson
    Scott Hudson
    2006-04-12

    Logged In: YES
    user_id=566420

    Let me provide a more specific example:
    For a particular engineering activity marked up in a
    procedure, there are several roles that need to be marked for
    specific steps. For each step, there is a Director and an
    Actor: one role that is supervising the step, and another
    that is performing the step.
    These roles are neither authors, nor editors and othercredit
    would really be a stretch.
    With a person element, it provides an abstract way of
    enabling this type of identification. With a class attribute
    or even role, it could be described more explicitly.

    Perhaps author, editor and othercredit should stay for
    attribution in the info elements, but I think a person
    element should be added for use in block and/or inlines
    either in addition to or instead of author, editor and
    othercredit.

    This element is not intended for attribution of the content,
    but for describing specific personnel requirements in
    technical documentation.

    Perhaps my previous examples were looking at additional
    posibilities for docbook extensions. This element will
    primarily be for the benefit of technical documentation.

     
  • Logged In: YES
    user_id=118135

    I agree that is would benefit the DocBook community to
    have a Person element. I strongly disagree that it is
    out of scope for DocBook.

    First, as far as I can see, what has been proposed is
    a Person element for use in the body of a document --
    not within the document info/metadata. So it is something
    quite different than Author, Editor, and Othercredit,
    and it was a mistake for this RFE to suggest it as a
    general replacement for those. I think Scott has already
    acknowledged that.

    Conversely, Author/Editor/Othercredit aren't appropriate
    for use in place of the proposed Person element. Author,
    Editor, and Othercredit all have the specific purpose
    of attributing credit to people who have contributed
    to the development of the document in which they are
    named or who have contributed to development of whatever
    is documented in it (a software application or whatever).

    Forget about the examples provided in the description
    for this RFE and consider the general case where a user
    simply wants to metion a certain person by name within a
    the body of a document -- a person who is not an author
    or editor of the document, and who has not contributed in
    any way to it nor to the development of the items
    documented in it. The potential use case is quite broad,
    and amounts to: Any time a user wants to mention a person
    by name in the body of a document. Along with the person's
    name, the user may want to include an e-mail address, an
    affiliation, and so on.

    How are users currently expected to mark that up? Without
    a Person wrapper that associates a Personname with Email,
    Affiliation, and so on, they can't. What happens instead
    is that each user who needs to do it resorts to some ah-hoc
    way of marking it up (wrapping it in Phrase with a
    role or something) that is their own best guess at how it
    ought to be modelled using the set of valid elements
    they are limited to. The result is is that we end up
    with N different users marking up the same person
    information N different ways.

    Having a Person element in DocBook would give all users
    a common way of associating additional information (Email,
    Affiliation, and so on) with a person, in cases where that
    person is mentioned by name within the body of a document.
    That does not seem to be at all out of scope for DocBook.

     
  • Norman Walsh
    Norman Walsh
    2006-04-12

    Logged In: YES
    user_id=81663

    Ok, so if the RFE isn't a request for new kinds of metadata
    elements, how is the existing personname element that can
    alread appear in para, phrase, and a whole bunch of other
    places, not sufficient for the purpose?

     
  • Logged In: YES
    user_id=118135

    The current personname element just identifies a name --
    what's lacking is way to associate that name with
    an affiliation, personblurb, email, and/or address.

    <para>Users doing DTD customization are encouraged to
    try the LiveDTD application developed by <person>
    <personname><firstname>Bob</firstname>
    <surname>Stayton</surname></personname>
    <email>bobs@sagehill.net</person>, which can be
    downloaded from his website.</para>

     
  • Norman Walsh
    Norman Walsh
    2006-04-12

    Logged In: YES
    user_id=81663

    So person is an inline:

    person = personname, (personblurb,affiliation,email,address)*

    and

    author = ((person, contrib*) | (orgname, ...))

    Does that mean we need an organization inline?

    I worry about the duplication of repeating each of this
    ancillary information with each mention of a person, but I
    suppose that's up to authors.

     
  • Scott Hudson
    Scott Hudson
    2006-04-12

    Logged In: YES
    user_id=566420

    Yes, that is the model I was anticipating. An organization
    inline would also be useful.

    I agree that duplicating the content in person for repeated
    uses in the same doc may be painful, and we may want to
    accommodate a later RFE for a personref, but that is not
    part of this RFE.

     
  • Logged In: YES
    user_id=118135

    > person = personname, (personblurb,affiliation,email,
    > address)*

    Yes, except I think you actually meant:

    person = personname, (personblurb|affiliation|email
    |address)*

    > and
    > author = ((person, contrib*) | (orgname, ...))

    I'm not sure there would what need or value there would
    be in changing the content of the author element if
    person is added. I don't think the author content model
    would needs to change. The author element could remain
    what is is now: a structure for associating the name of
    an author with other information, person would be for
    associating the name of a person with other information.

    > Does that mean we need an organization inline?

    I don't think it necessarily does. Though I'm not saying
    I think it wouldn't be useful. I just think if it's
    considered at all, perhaps is should be in a separate RFE.

    > I worry about the duplication of repeating each of this
    > ancillary information with each mention of a person, but
    > I suppose that's up to authors.

    Yeah, I think so. Doc authors can make use of entities or
    some other macro system that allows them to define the
    person instance once and then reference that definition
    each time.

     
  • Norman Walsh
    Norman Walsh
    2006-04-19

    • status: open --> open-accepted
     
  • Norman Walsh
    Norman Walsh
    2006-04-19

    Logged In: YES
    user_id=81663

    Accepted at 19 Apr 2006 TC telcon.

    Render = inline; sometimes collected in the "back of the
    book" as a list of orgs and/or persons.

    org = orgname, (address|affiliation|email|orgdiv)*
    person = personname, (address|affiliation|email|personblurb)*

     
  • Norman Walsh
    Norman Walsh
    2006-06-02

    • status: open-accepted --> closed-fixed
     
  • Norman Walsh
    Norman Walsh
    2006-06-02

    Logged In: YES
    user_id=81663

    Added in 5.0b6.