Loading ...
Sorry, an error occurred while loading the content.
 

Descriptions (was: Examples)

Expand Messages
  • Jenni A. Merrifield
    ... [...snip...] ... Rather than including the heading text in the body of the descriptive
    Message 1 of 1 , Apr 12 6:05 PM
      <quote who="Frugal" when="Wed, 7 Apr 2004 10:56:34 +0100 (BST)">
      > <quote who="Keith Davies">
      > > On Tue, Apr 06, 2004 at 11:56:32AM +0100, Frugal wrote:
      > > >
      > > > <description>
      > > > <brief>One line desc</brief>
      > > > <detailed><h3>Description</h3><p>This is the long desc</p></detailed>
      > >
      > > Don't embed specific headings in it like this, I think. I can't think
      > > of *too* many cases where entities will be complex enough to have their
      > > own headings. The few that do would probably be better off with a more
      > > generic <h> -- that can be picked up and formatted as needed for
      > > whatever level it appears at. For instance, if we were dumping
      > > everything to HTML and each class gets its own page, we might make them
      > > <h2> (<h3> for nested ones); if they all go on a single page, they might
      > > be <h3> or <h4> (with corresponding values for nested ones).

      [...snip...]

      > Like you I can not think of any reason to have headings in a description,
      > but I can certainly see a use for lists, emphasis etc.

      Rather than including the "heading" text in the body of the descriptive
      text, it might be more useful to allow multiple descriptions for dividing up
      the type of information for an entity. This would allow some OS to display
      data with headings based on the sub-division type/kind - such as how feats,
      skills, races, classes, &c. are shown in the PHB (e.g. for feats - there is a
      brief one-line definition with no header of its own, followed by an optional
      Prerequisites section, followed by a required Benefits section, followed by
      an optional Special section.

      This could be achieved like this, could it not:

      <entity id="feat.precise-shot">
      <name>Precise Shot</name>
      <prereq kind="feat" key="feat.point-blank-shot" operator="<"
      operand="1"/>
      <descriptions>
      <description kind="definition">You are skilled at timing and aiming
      ranged attacks.</description>
      <description kind="benefit">You can shoot or throw ranged weapons at an
      opponent engaged in melee without taking the standard -4 penalty on your
      attack roll.</description>
      <description kind="special">A character may gain this feat multiple
      times. Its effects stack.</description>
      </descriptions>
      <types>
      <type>feat</type>
      <type>general</type>
      <type>fighter</type>
      </types>
      </entity>


      Note that, there should not be a need for a specific tag for the
      description of feat prerequisites, prestige class requirements, and the like
      since the required values can be obtained from the name values of any feats,
      variables, &c. mentioned in relevant <prereq ...> tags.

      This does assume that there will be <prereq ...> tags for roleplaying
      prerequisites, such as the following requirement for the assassin PrC: "The
      character must kill someone for no other reason than to join the assassins."
      As they're usually noted as "special" that could be used as the kind. E.g.:

      <prereq kind="special">The character must kill someone for no other reason
      than to join the assassins.</prereq>


      > Out of interest what do people thin is the best way to allow an arbitrary
      > set of tags under a <description> tag ?
      >
      > - Explicitly specify which subset of HTML tags we allow?
      >
      > - include the XHTML schema and demand that the nested tags are all in the
      > xhtml: namespace?
      >
      > - Can we even say "allow any valid XML content as a child of this tag and
      > do not validate it against the current schema"? and if we can do we want
      > to?
      >

      I'd be inclined to go with option 2 (include the XHTML schema) but I'd also
      suggest that any documentation should advise best practices that are more
      akin to option 1 (explicitly specify which subset of HTML tags we allow).
      That is, technically anything goes, but, for the purposes of separating
      content from presentation, only a small subset of tags are actually
      recommended.

      Off the cuff, I'd restrict the "recommended HTML tags" to the following:

      * CHARACTER: <em>; <strong>; <sub>; <sup>; <cite>;
      * BLOCK: <p>; <pre>; <blockquote>;
      * LIST: <ul>; <ol>; <li>; <dl>; <dt>; <dd>;
      * OTHER: <br>; <a>;

      I debated whether or not to include <a> in that list. I'm not really sure
      it should be there

      Jenni

      --
      Jenni A. M. Merrifield (strawberry @ jamm . com)
      Software User Experience Professional
      Designing to Requirements and walking on Water is EASY. . .
      . . . So long as both are Frozen.
      --
    Your message has been successfully submitted and would be delivered to recipients shortly.