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

Re: [pcgen-xml] Re: XML Design Guidelines

Expand Messages
  • Keith Davies
    ... I d like to have a regular hierarchical structure -- that s what XML does best -- but the nature of the data is unfortunately unhierarchical for reference
    Message 1 of 13 , Feb 4, 2002
    • 0 Attachment
      giliath01 wrote on Mon Feb 4 20:30:32 2002:
      >
      > > <classifications>
      > > <race-list id="race-list.fr" name="Forgotten R. Races"/>
      > > <race-list id="race-list.fr.elf" name="Elven Races"/>
      > > <race-list id='race-list.fr.dwarf" name="Dwarven Races"/>
      > > </classifications>
      > >
      > > <assignments>
      > > <list-entries list-id="race-list.fr">
      > > <entry refid="race-list.fr.human"/>
      > > <entry refid="race-list.fr.elf"/>
      > > <entry refid="race-list.fr.human"/>
      > > </list-entries>
      > > <list-entries list-id="race-list.fr.elf">
      > > <entry refid="race.elf"/>
      > > <entry refid="race.elf.high"/>
      > > <entry refid="race.elf.drow"/>
      > > <entry refid="race.elf.sea"/>
      > > </list-entries>
      > > </assignments>
      > > </pcgen>
      >
      > You reference and your classifications have definitive types as
      > in <race> or <race-list> and I like that, but your assignments
      > don't and that means that it is going to be hard to map back
      > from a <entry refid="race.dwarf"> to the type unless you are
      > planning on keeping a global list of all object ids.

      I'd like to have a regular hierarchical structure -- that's what XML
      does best -- but the nature of the data is unfortunately unhierarchical
      for reference information. So far as I can see, no own thing 'owns'
      the description of 'longsword', at least in a meaningful way. Because
      of the number of references made to object definitions, the IDs will be
      needed. That's why they're there -- IDs, by their nature, are meant
      to be used in this fashion.

      > Perhaps something like this would work:
      >
      > <race id="race.elf" name="Elf"/>
      >
      > <race-list id="race-list.fr.elf">
      > <race-ref id="race.elf" />
      > </race-list>
      >
      > <race-list id="race-list.fr">
      > <race-list-ref id="race-list.fr.elf />
      > </race-list>

      I considered something like this once, for another schema. Frankly,
      it was a pain in the ass to use. <ref> (or <entry>, above) tend to
      be fairly obvious in context. That it is a reference to a race can
      be inferred by the ID (<entry refid="race.elf"/>, f'rex) and context.
      Having to use specifical <*-ref> types got to be annoying, especially
      when they're all doing the same thing. I could see some small gain
      in that it describes the data in higher detail, but -- at this point --
      I don't think it's gains enough to be worth the trouble.

      Normally I wouldn't have the assignment elements as I do -- I'd do
      basically what you suggest.

      <race-list id="race-list.fr.elf">
      <ref refid="race.fr.elf.gold"/>
      <ref refid="race.fr.elf.moon"/>
      </race-list>

      <race-list id="race-list.fr">
      <ref refid="race-list.fr.elf"/>
      <ref refid="race-list.fr.dwarf"/>
      </race-list>

      does tend to be easier to understand, and it's how I'd normally do
      it. However -- and this is a big however -- it must be possible for
      other documents to add to lists. For instance, a new book of spells
      adds spells to the normal schools, domains, and other lists. I don't
      want to have to modify the lists themselves for a few reasons. One
      is that it causes too much traffic on the files describing those
      lists, and contention when checking the changes in... if you get too
      many people trying to edit a single file at a single time, CVS can
      sometimes have trouble with it. I'd like to avoid that. I can't
      put the list references in <spell>, either, because when people try
      to customize things for a new campaign (by adding new spell lists,
      domains, etc) there'll be contention for the files where the spells
      are described... and I probably don't care about the changes someone
      else does for their campaign, and outside of curiosity, they probably
      don't care about mine.

      By breaking the assignment out of both elements into a new one, it
      removes the hard binding between the lists and the objects being
      referenced in them. This allows me to have a file structure like:

      $PCGEN/data/wotc/phb/spell-lists.xml
      $PCGEN/data/woth/phb/spells.xml
      $PCGEN/data/sss/rnr/spell-lists.xml
      $PCGEN/data/sss/rnr/spells.xml
      $PCGEN/data/kjd/trilania/spell-lists.xml
      $PCGEN/data/kjd/trilania/spells.xml

      Each of the spells.xml files describe spells; the spell-lists.xml
      files associate the spells with the lists. By keeping my
      assignments in my own files (the kjd/trilania branch), I don't
      have to worry at all about my changes being lost to updates, as
      would happen when someone updates the description for /fireball/
      and takes out the reference to my BlowEmUp spell list, or remove
      reference to my spells in the Abjuration spell list... it maintains
      a nice independence between the files, but still allows the data
      associations. I can add spells the the normal Abjuration spell
      list without disturbing anyone else, and I can add core spells to
      my spell lists without disturbing anyone else.

      This is a good thing, IMO.

      It also allows me to drop certain things without damaging anything.
      I can simply not load wotc/phb/spell-lists.xml -- it'll cost me the
      spell lists defined in the core rules, but allow me to continue using
      my own, without having bogus references.

      This is also a good thing.

      > This allows you to keep a clearer relationship and also allows you to
      > prevent some weird errors by using a validating dtd like:
      >
      > <!ELEMENT race-list (race-ref|race-list-ref)* >
      > <!ATTLIST race-list id ID >
      >
      > <!ELEMENT race-ref EMPTY>
      > <!ATTLIST race-ref id IDREF>
      >
      > <!ELEMENT race-list-ref EMPTY>
      > <!ATTLIST race-list-ref id IDREF>
      >
      > Furthermore, you might not want to seperate them into generic
      > element types like: <reference> <classification> <assignments>
      > because that is implied by how you use them, because <race> <class>
      > <weapon> are all reference elements by design.

      This is true. However, I want to be able to browse the files in a
      reasonable manner. When I collapse the files (I've got a very simple
      XSLT script that'll collect all the stuff into once place -- a few
      <include>s and <ref>s in my campaign file can cause a significant
      subset of the data to be loaded, quite simply) and open the result in
      gxmlviewer or the like, I can quickly browse the results to see what's
      present. Nice to be able to do. However, if I leave it at a higher
      level -- lose the <reference> and similar elements -- I can end up with
      hundreds of near top-level elements. Makes browsing a bit of a chore.

      Incidentally, I think I'll add the common attributes (@id and @name) to
      the <reference> and <assignment> elements; it'd give me some way to
      tell them apart, and it actually is useful information...

      <reference id="reference.phb.weapons" name="PHB Weapons" />

      would be useful when browsing.

      Now, *ALL* of the above aside, I don't expect the data to be represented
      in memory in the same way it's represented in files. Part of the reason
      I broke out the reference, classification, and assignment information
      the way I have is so the files describe *how the data is to be manipulated*.
      I'm not sure if I conveyed this properly in my document. What I expect
      is that the data will be transformed on loading, into a structure rather
      similar to what you've described earlier.

      For instance, the weapon lists I've described in the files have
      <list-entries> associated with them. I expect that the data will be
      transformed from the file form (documented) to an internal form like

      <weapon-list id="weapon-list.axes" name="Axes">
      <ref refid="weapon.battleaxe"/>
      <ref refid="weapon.handaxe"/>
      <ref refid="weapon.greataxe"/>
      </weapon-list>

      and so on. However, this is (theoretically) beyond the scope of this
      project... it's up to the front-end folks to figure out what they
      want to do -- we just have to be able to represent the data in a useful
      way. I do expect to make recommendations to them, though.


      Keith
      --
      Keith Davies
      kjdavies@...

      Logan: "I don't think it's a good idea."
      Raven: "The vote is three to one against you -- me, the crystal ball,
      and the little voices in your head."
    • Peter Kahle
      While I understand your point in this, I think perhaps there should be some sort of hints to software that certain types are expected at certain places. Using
      Message 2 of 13 , Feb 5, 2002
      • 0 Attachment
        While I understand your point in this, I think perhaps there should be
        some sort of hints to software that certain types are expected at
        certain places. Using the below example, maybe something like:

        <list-entries list-type='race-list' ref-type='race' list-id='race-list.fr'>
        <entry refid="race-list.fr.human"/>
        <entry refid="race-list.fr.elf"/>
        <entry refid="race-list.fr.human"/>
        </list-entries>

        So then we can have software verify that the element referenced by
        'race-list.fr' is a race-list element, and every referenced element in
        an entry in this list is a race element.

        I guess, looking at it, it doesn't buy you much, but I can see it being
        useful debugging problems people may have.
        P


        On Mon, Feb 04, 2002 at 09:43:22PM -0800, Keith Davies wrote:
        > giliath01 wrote on Mon Feb 4 20:30:32 2002:
        > >
        > > > <classifications>
        > > > <race-list id="race-list.fr" name="Forgotten R. Races"/>
        > > > <race-list id="race-list.fr.elf" name="Elven Races"/>
        > > > <race-list id='race-list.fr.dwarf" name="Dwarven Races"/>
        > > > </classifications>
        > > >
        > > > <assignments>
        > > > <list-entries list-id="race-list.fr">
        > > > <entry refid="race-list.fr.human"/>
        > > > <entry refid="race-list.fr.elf"/>
        > > > <entry refid="race-list.fr.human"/>
        > > > </list-entries>
        > > > <list-entries list-id="race-list.fr.elf">
        > > > <entry refid="race.elf"/>
        > > > <entry refid="race.elf.high"/>
        > > > <entry refid="race.elf.drow"/>
        > > > <entry refid="race.elf.sea"/>
        > > > </list-entries>
        > > > </assignments>
        > > > </pcgen>
        > >
        > > You reference and your classifications have definitive types as
        > > in <race> or <race-list> and I like that, but your assignments
        > > don't and that means that it is going to be hard to map back
        > > from a <entry refid="race.dwarf"> to the type unless you are
        > > planning on keeping a global list of all object ids.
        >
        > I'd like to have a regular hierarchical structure -- that's what XML
        > does best -- but the nature of the data is unfortunately unhierarchical
        > for reference information. So far as I can see, no own thing 'owns'
        > the description of 'longsword', at least in a meaningful way. Because
        > of the number of references made to object definitions, the IDs will be
        > needed. That's why they're there -- IDs, by their nature, are meant
        > to be used in this fashion.
        >
        > > Perhaps something like this would work:
        > >
        > > <race id="race.elf" name="Elf"/>
        > >
        > > <race-list id="race-list.fr.elf">
        > > <race-ref id="race.elf" />
        > > </race-list>
        > >
        > > <race-list id="race-list.fr">
        > > <race-list-ref id="race-list.fr.elf />
        > > </race-list>
        >
        > I considered something like this once, for another schema. Frankly,
        > it was a pain in the ass to use. <ref> (or <entry>, above) tend to
        > be fairly obvious in context. That it is a reference to a race can
        > be inferred by the ID (<entry refid="race.elf"/>, f'rex) and context.
        > Having to use specifical <*-ref> types got to be annoying, especially
        > when they're all doing the same thing. I could see some small gain
        > in that it describes the data in higher detail, but -- at this point --
        > I don't think it's gains enough to be worth the trouble.
        >
        > Normally I wouldn't have the assignment elements as I do -- I'd do
        > basically what you suggest.
        >
        > <race-list id="race-list.fr.elf">
        > <ref refid="race.fr.elf.gold"/>
        > <ref refid="race.fr.elf.moon"/>
        > </race-list>
        >
        > <race-list id="race-list.fr">
        > <ref refid="race-list.fr.elf"/>
        > <ref refid="race-list.fr.dwarf"/>
        > </race-list>
        >
        > does tend to be easier to understand, and it's how I'd normally do
        > it. However -- and this is a big however -- it must be possible for
        > other documents to add to lists. For instance, a new book of spells
        > adds spells to the normal schools, domains, and other lists. I don't
        > want to have to modify the lists themselves for a few reasons. One
        > is that it causes too much traffic on the files describing those
        > lists, and contention when checking the changes in... if you get too
        > many people trying to edit a single file at a single time, CVS can
        > sometimes have trouble with it. I'd like to avoid that. I can't
        > put the list references in <spell>, either, because when people try
        > to customize things for a new campaign (by adding new spell lists,
        > domains, etc) there'll be contention for the files where the spells
        > are described... and I probably don't care about the changes someone
        > else does for their campaign, and outside of curiosity, they probably
        > don't care about mine.
        >
        > By breaking the assignment out of both elements into a new one, it
        > removes the hard binding between the lists and the objects being
        > referenced in them. This allows me to have a file structure like:
        >
        > $PCGEN/data/wotc/phb/spell-lists.xml
        > $PCGEN/data/woth/phb/spells.xml
        > $PCGEN/data/sss/rnr/spell-lists.xml
        > $PCGEN/data/sss/rnr/spells.xml
        > $PCGEN/data/kjd/trilania/spell-lists.xml
        > $PCGEN/data/kjd/trilania/spells.xml
        >
        > Each of the spells.xml files describe spells; the spell-lists.xml
        > files associate the spells with the lists. By keeping my
        > assignments in my own files (the kjd/trilania branch), I don't
        > have to worry at all about my changes being lost to updates, as
        > would happen when someone updates the description for /fireball/
        > and takes out the reference to my BlowEmUp spell list, or remove
        > reference to my spells in the Abjuration spell list... it maintains
        > a nice independence between the files, but still allows the data
        > associations. I can add spells the the normal Abjuration spell
        > list without disturbing anyone else, and I can add core spells to
        > my spell lists without disturbing anyone else.
        >
        > This is a good thing, IMO.
        >
        > It also allows me to drop certain things without damaging anything.
        > I can simply not load wotc/phb/spell-lists.xml -- it'll cost me the
        > spell lists defined in the core rules, but allow me to continue using
        > my own, without having bogus references.
        >
        > This is also a good thing.
        >
        > > This allows you to keep a clearer relationship and also allows you to
        > > prevent some weird errors by using a validating dtd like:
        > >
        > > <!ELEMENT race-list (race-ref|race-list-ref)* >
        > > <!ATTLIST race-list id ID >
        > >
        > > <!ELEMENT race-ref EMPTY>
        > > <!ATTLIST race-ref id IDREF>
        > >
        > > <!ELEMENT race-list-ref EMPTY>
        > > <!ATTLIST race-list-ref id IDREF>
        > >
        > > Furthermore, you might not want to seperate them into generic
        > > element types like: <reference> <classification> <assignments>
        > > because that is implied by how you use them, because <race> <class>
        > > <weapon> are all reference elements by design.
        >
        > This is true. However, I want to be able to browse the files in a
        > reasonable manner. When I collapse the files (I've got a very simple
        > XSLT script that'll collect all the stuff into once place -- a few
        > <include>s and <ref>s in my campaign file can cause a significant
        > subset of the data to be loaded, quite simply) and open the result in
        > gxmlviewer or the like, I can quickly browse the results to see what's
        > present. Nice to be able to do. However, if I leave it at a higher
        > level -- lose the <reference> and similar elements -- I can end up with
        > hundreds of near top-level elements. Makes browsing a bit of a chore.
        >
        > Incidentally, I think I'll add the common attributes (@id and @name) to
        > the <reference> and <assignment> elements; it'd give me some way to
        > tell them apart, and it actually is useful information...
        >
        > <reference id="reference.phb.weapons" name="PHB Weapons" />
        >
        > would be useful when browsing.
        >
        > Now, *ALL* of the above aside, I don't expect the data to be represented
        > in memory in the same way it's represented in files. Part of the reason
        > I broke out the reference, classification, and assignment information
        > the way I have is so the files describe *how the data is to be manipulated*.
        > I'm not sure if I conveyed this properly in my document. What I expect
        > is that the data will be transformed on loading, into a structure rather
        > similar to what you've described earlier.
        >
        > For instance, the weapon lists I've described in the files have
        > <list-entries> associated with them. I expect that the data will be
        > transformed from the file form (documented) to an internal form like
        >
        > <weapon-list id="weapon-list.axes" name="Axes">
        > <ref refid="weapon.battleaxe"/>
        > <ref refid="weapon.handaxe"/>
        > <ref refid="weapon.greataxe"/>
        > </weapon-list>
        >
        > and so on. However, this is (theoretically) beyond the scope of this
        > project... it's up to the front-end folks to figure out what they
        > want to do -- we just have to be able to represent the data in a useful
        > way. I do expect to make recommendations to them, though.
        >
        >
        > Keith
        > --
        > Keith Davies
        > kjdavies@...
        >
        > Logan: "I don't think it's a good idea."
        > Raven: "The vote is three to one against you -- me, the crystal ball,
        > and the little voices in your head."
        >
        >
        > To unsubscribe from this group, send an email to:
        > pcgen-xml-unsubscribe@yahoogroups.com
        >
        >
        >
        > Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/
        >
        >

        --

        Those who would give up essential Liberty to purchase a little temporary
        safety, deserve neither Liberty nor safety.
        -- Ben Franklin

        || Peter M Kahle Jr || PGP Public Key on Keyservers ||
        || pkahle@... || http://pops.dyndns.com/~pkahle/ ||
        ##===============================##======================================##
      • Peter Kahle
        Gah. I screwed up... text all stays the same, but my example changes:
        Message 3 of 13 , Feb 5, 2002
        • 0 Attachment
          Gah. I screwed up... text all stays the same, but my example changes:

          <list-entries list-type='race-list' ref-type='race-list'
          list-id='race-list.fr'>
          <entry refid="race-list.fr.human"/>
          <entry refid="race-list.fr.elf"/>
          <entry refid="race-list.fr.human"/>
          </list-entries>
          <list-entries list-type='race-list' ref-type='race'
          list-id='race-list.fr.elf'>
          <entry refid="race.elf"/>
          <entry refid="race.elf.high"/>
          <entry refid="race.elf.drow"/>
          <entry refid="race.elf.sea"/>
          </list-entries>

          Also, now looking at it, might it be a good idea to give a hint to
          either the list-entries or the entrys themselves as to what to do with
          the entries? either add or list, or some other semantic? This might
          replace my version above, to look like:

          <list-entries list-type='race-list' ref-type='race'
          list-id='race-list.fr'>
          <entry refid="race-list.fr.human" type='list'/>
          <entry refid="race-list.fr.elf" type='list'/>
          <entry refid="race-list.fr.human" type='list'/>
          <entry refid="race.custom.foo" type='add'/>
          </list-entries>

          What I'm thinking about is making it so the processor doesn't need added
          intelligence to figure out what to do with the entry types. What I'm
          trying to avoid is, for example, an XSLT sheet generating (incorrectly)
          the following from this last entry:

          <race-list id='race-list.fr'>
          <race-list id='race-list.fr.human'>
          <race .../>
          ...
          </race-list>
          <race-list id="race-list.fr.elf">
          <race>
          ...
          </race-list>
          <race-list id='race-list.fr.human'>
          <race .../>
          ...
          </race-list>
          <race id='race.custom.foo'/>
          </race-list>

          Anyway, I think a flattened set of lists is vastly preferable,
          especially if there's any possibility of a race containing reference to
          another race (favored enemy maybe?) which would make a search for all
          races or references to races contained in the top level race-list give
          undesireable results.

          Anyway, I'm still fleshing this out in my head at this point. I may send
          some more formalized way of looking at it at some point in the future.
          P

          On Tue, Feb 05, 2002 at 12:20:20PM -0600, Peter Kahle wrote:
          > While I understand your point in this, I think perhaps there should be
          > some sort of hints to software that certain types are expected at
          > certain places. Using the below example, maybe something like:
          >
          > <list-entries list-type='race-list' ref-type='race' list-id='race-list.fr'>
          > <entry refid="race-list.fr.human"/>
          > <entry refid="race-list.fr.elf"/>
          > <entry refid="race-list.fr.human"/>
          > </list-entries>
          >
          > So then we can have software verify that the element referenced by
          > 'race-list.fr' is a race-list element, and every referenced element in
          > an entry in this list is a race element.
          >
          > I guess, looking at it, it doesn't buy you much, but I can see it being
          > useful debugging problems people may have.
          > P
          >
          >
        • Keith Davies
          ... Well, given that @list-id points at a , I don t think it s necessary to say as much in the other attributes. We could leave it as
          Message 4 of 13 , Feb 5, 2002
          • 0 Attachment
            Peter Kahle wrote on Tue Feb 5 10:48:15 2002:
            >
            > Gah. I screwed up... text all stays the same, but my example changes:
            >
            > <list-entries list-type='race-list' ref-type='race-list'
            > list-id='race-list.fr'>
            > <entry refid="race-list.fr.human"/>
            > <entry refid="race-list.fr.elf"/>
            > <entry refid="race-list.fr.human"/>
            > </list-entries>
            > <list-entries list-type='race-list' ref-type='race'
            > list-id='race-list.fr.elf'>
            > <entry refid="race.elf"/>
            > <entry refid="race.elf.high"/>
            > <entry refid="race.elf.drow"/>
            > <entry refid="race.elf.sea"/>
            > </list-entries>

            Well, given that @list-id points at a <race-list>, I don't think it's
            necessary to say as much in the other attributes. We could leave it
            as

            <list-entries list-id="race-list.fr.elf">
            <ref refid="race.elf"/>
            <ref refid="race.elf.high"/>
            <ref refid="race.elf.drow"/>
            <ref refid="race.elf.sea"/>
            </list-entries>

            Note that I changed the <entry> to a simple <ref>... I'd like to keep
            the number of element types down, if I can, and <entry> doesn't tell
            me anything a <ref> doesn't.

            > Also, now looking at it, might it be a good idea to give a hint to
            > either the list-entries or the entrys themselves as to what to do with
            > the entries? either add or list, or some other semantic? This might
            > replace my version above, to look like:

            This I could see a benefit to, because references to lists often will
            be treated differently. How 'bout

            <list-entries list-id="race-list.fr">
            <list-ref refid="race-list.fr.human"/>
            <list-ref refid="race-list.fr.elf"/>
            <list-ref refid="race-list.fr.dwarf"/>
            <ref refid="race.custom.gimblatt"/>
            </list-entries>

            This makes it obvious to the processor that the reference is pointing
            to a list.

            Actually, tacky as it is sometimes, I'm almost inclined to use some
            IDREFS attributes:

            <list-entries list-id="race-list.fr">
            <list-refs refids="race-list.fr.human race-list.fr.elf race-list.fr.dwarf"/>
            <refs refids="race.custom.gimblatt race.custom.donalti"/>
            </list-entries>

            but I think it wouldn't be a good idea.

            > <list-entries list-type='race-list' ref-type='race'
            > list-id='race-list.fr'>
            > <entry refid="race-list.fr.human" type='list'/>
            > <entry refid="race-list.fr.elf" type='list'/>
            > <entry refid="race-list.fr.human" type='list'/>
            > <entry refid="race.custom.foo" type='add'/>
            > </list-entries>
            >
            > What I'm thinking about is making it so the processor doesn't need added
            > intelligence to figure out what to do with the entry types. What I'm
            > trying to avoid is, for example, an XSLT sheet generating (incorrectly)
            > the following from this last entry:
            >
            > <race-list id='race-list.fr'>
            > <race-list id='race-list.fr.human'>
            > <race .../>
            > ...
            > </race-list>
            > <race-list id="race-list.fr.elf">
            > <race>
            > ...
            > </race-list>
            > <race-list id='race-list.fr.human'>
            > <race .../>
            > ...
            > </race-list>
            > <race id='race.custom.foo'/>
            > </race-list>

            It's actually not hard to create an XSLT script that'll correctly handle
            it (template modes are *so* bloody useful sometimes). I'd have it run in
            at least two passes, though -- one to denormalize the data, and a second
            to tidy it up (remove duplicates and whatnot).


            Keith
            --
            Keith Davies
            kjdavies@...

            Logan: "I don't think it's a good idea."
            Raven: "The vote is three to one against you -- me, the crystal ball,
            and the little voices in your head."
          • Peter Kahle
            ... *snip* ... Well, given what you said above about keeping the number of elements down (did you mean attributes?) why not define an attribute, call it
            Message 5 of 13 , Feb 5, 2002
            • 0 Attachment
              On Tue, Feb 05, 2002 at 11:36:26AM -0800, Keith Davies wrote:
              > Peter Kahle wrote on Tue Feb 5 10:48:15 2002:

              *snip*

              > Note that I changed the <entry> to a simple <ref>... I'd like to keep
              > the number of element types down, if I can, and <entry> doesn't tell
              > me anything a <ref> doesn't.
              >
              > > Also, now looking at it, might it be a good idea to give a hint to
              > > either the list-entries or the entrys themselves as to what to do with
              > > the entries? either add or list, or some other semantic? This might
              > > replace my version above, to look like:
              >
              > This I could see a benefit to, because references to lists often will
              > be treated differently. How 'bout
              >
              > <list-entries list-id="race-list.fr">
              > <list-ref refid="race-list.fr.human"/>
              > <list-ref refid="race-list.fr.elf"/>
              > <list-ref refid="race-list.fr.dwarf"/>
              > <ref refid="race.custom.gimblatt"/>
              > </list-entries>
              >
              > This makes it obvious to the processor that the reference is pointing
              > to a list.

              Well, given what you said above about keeping the number of elements
              down (did you mean attributes?) why not define an attribute, call it
              reftype, with two possible values (at this point) "item" and "list" (I'm
              open for suggestions on item, but it's the best I could come up with on
              short notice.) and default it to item. That way, you get the same effect
              as above, without the extra element, and with only a little more typing:

              <list-entries list-id="race-list.fr">
              <ref refid="race-list.fr.human" reftype="list"/>
              <ref refid="race-list.fr.elf" reftype="list"/>
              <ref refid="race-list.fr.dwarf" reftype="list"/>
              <ref refid="race.custom.gimblatt"/>
              </list-entries>

              I don't care too much about this, but there's a certain elegance in
              being able to say that each list-entries element can contain only ref
              elements.

              > Actually, tacky as it is sometimes, I'm almost inclined to use some
              > IDREFS attributes:
              >
              > <list-entries list-id="race-list.fr">
              > <list-refs refids="race-list.fr.human race-list.fr.elf race-list.fr.dwarf"/>
              > <refs refids="race.custom.gimblatt race.custom.donalti"/>
              > </list-entries>
              >
              > but I think it wouldn't be a good idea.

              I agree.

              > > <list-entries list-type='race-list' ref-type='race'
              > > list-id='race-list.fr'>
              > > <entry refid="race-list.fr.human" type='list'/>
              > > <entry refid="race-list.fr.elf" type='list'/>
              > > <entry refid="race-list.fr.human" type='list'/>
              > > <entry refid="race.custom.foo" type='add'/>
              > > </list-entries>
              > >
              > > What I'm thinking about is making it so the processor doesn't need added
              > > intelligence to figure out what to do with the entry types. What I'm
              > > trying to avoid is, for example, an XSLT sheet generating (incorrectly)
              > > the following from this last entry:
              > >
              > > <race-list id='race-list.fr'>
              > > <race-list id='race-list.fr.human'>
              > > <race .../>
              > > ...
              > > </race-list>
              > > <race-list id="race-list.fr.elf">
              > > <race>
              > > ...
              > > </race-list>
              > > <race-list id='race-list.fr.human'>
              > > <race .../>
              > > ...
              > > </race-list>
              > > <race id='race.custom.foo'/>
              > > </race-list>
              >
              > It's actually not hard to create an XSLT script that'll correctly handle
              > it (template modes are *so* bloody useful sometimes). I'd have it run in
              > at least two passes, though -- one to denormalize the data, and a second
              > to tidy it up (remove duplicates and whatnot).

              Yeah, I found out about template modes by trial-and-error a few weeks
              back. very useful.
              But in general, you seem to have more experience with this stuff than I
              do, so I'll defer to your decisions. (and keep offering suggestions when
              they strike me.)
              P

              >
              >
              > Keith
              > --
              > Keith Davies
              > kjdavies@...
              >
              > Logan: "I don't think it's a good idea."
              > Raven: "The vote is three to one against you -- me, the crystal ball,
              > and the little voices in your head."
              >
              >
              > To unsubscribe from this group, send an email to:
              > pcgen-xml-unsubscribe@yahoogroups.com
              >
              >
              >
              > Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/
              >
              >

              --

              Those who would give up essential Liberty to purchase a little temporary
              safety, deserve neither Liberty nor safety.
              -- Ben Franklin

              || Peter M Kahle Jr || PGP Public Key on Keyservers ||
              || pkahle@... || http://pops.dyndns.com/~pkahle/ ||
              ##===============================##======================================##
            • Keith Davies
              ... I m trying to keep them down, but not to a minimum. When it really does describe something different (such as a reference to a list rather than an object)
              Message 6 of 13 , Feb 5, 2002
              • 0 Attachment
                Peter Kahle wrote on Tue Feb 5 12:02:39 2002:
                >
                > On Tue, Feb 05, 2002 at 11:36:26AM -0800, Keith Davies wrote:
                > > Peter Kahle wrote on Tue Feb 5 10:48:15 2002:
                >
                > *snip*
                >
                > > Note that I changed the <entry> to a simple <ref>... I'd like to keep
                > > the number of element types down, if I can, and <entry> doesn't tell
                > > me anything a <ref> doesn't.
                > >
                > > > Also, now looking at it, might it be a good idea to give a hint to
                > > > either the list-entries or the entrys themselves as to what to do with
                > > > the entries? either add or list, or some other semantic? This might
                > > > replace my version above, to look like:
                > >
                > > This I could see a benefit to, because references to lists often will
                > > be treated differently. How 'bout
                > >
                > > <list-entries list-id="race-list.fr">
                > > <list-ref refid="race-list.fr.human"/>
                > > <list-ref refid="race-list.fr.elf"/>
                > > <list-ref refid="race-list.fr.dwarf"/>
                > > <ref refid="race.custom.gimblatt"/>
                > > </list-entries>
                > >
                > > This makes it obvious to the processor that the reference is pointing
                > > to a list.
                >
                > Well, given what you said above about keeping the number of elements
                > down (did you mean attributes?) why not define an attribute, call it
                > reftype, with two possible values (at this point) "item" and "list" (I'm
                > open for suggestions on item, but it's the best I could come up with on
                > short notice.) and default it to item. That way, you get the same effect
                > as above, without the extra element, and with only a little more typing:
                >
                > <list-entries list-id="race-list.fr">
                > <ref refid="race-list.fr.human" reftype="list"/>
                > <ref refid="race-list.fr.elf" reftype="list"/>
                > <ref refid="race-list.fr.dwarf" reftype="list"/>
                > <ref refid="race.custom.gimblatt"/>
                > </list-entries>
                >
                > I don't care too much about this, but there's a certain elegance in
                > being able to say that each list-entries element can contain only ref
                > elements.

                I'm trying to keep them down, but not to a minimum. When it really
                does describe something different (such as a reference to a list rather
                than an object) I'd rather have a different element.

                For instance, at one point I was tempted to just make the classification
                objects <list>s -- regardless of what they were listing. Makes it nice,
                simple, and consistent. All good things. However, the ability to find
                lists of certain things (such as of weapons, or spells, and so on) made
                that a poor decision, so I decided not to go that way.

                I'm still trying to figure out a nice way of doing spell assignments --
                getting them into the right list is easy, but specifying the levels in
                a useful manner is annoying. The list assignment will work much like
                above, and for the same reasons (the assignment is separate from the
                reference and classification objects to reduce the impact of adding
                new reference or classification objects).

                I could do something like

                <spell-list id="spell-list.abjuration" />
                <list-entries list-id="spell-list.abjuration">
                <list-ref refid="spells-list.abjuration.0" />
                <list-ref refid="spells-list.abjuration.1" />
                <list-ref refid="spells-list.abjuration.2" />
                <list-ref refid="spells-list.abjuration.3" />
                <list-ref refid="spells-list.abjuration.4" />
                <list-ref refid="spells-list.abjuration.5" />
                <list-ref refid="spells-list.abjuration.6" />
                <list-ref refid="spells-list.abjuration.7" />
                <list-ref refid="spells-list.abjuration.8" />
                <list-ref refid="spells-list.abjuration.9" />
                </list-entries>

                <spell-list id="spell-list.abjuration.0" level="0"/>
                <list-entries list-id="spell-list.abjuration.0">
                <ref />
                <ref />
                <ref />
                </list-entries>

                Which does have the happy effect of breaking the lists down by level as
                well... it seems disatisfying, though. I could do

                <spell-list id="spell-list.abjuration" />
                <list-entries list-id="spell-list.abjuration">
                <spell-ref refid="spell.shield" level="1"/>
                <!-- ... -->
                </list-entries>

                but that would get *really* old, *really* fast, and doesn't necessarily
                gain us anything. I suppose I could do something like

                <spell-list id="spell-list.abjuration">
                <level-list id="spell-list.abjuration.0" level="0" />
                <level-list id="spell-list.abjuration.1" level="1" />
                <level-list id="spell-list.abjuration.2" level="2" />
                <level-list id="spell-list.abjuration.3" level="3" />
                <level-list id="spell-list.abjuration.4" level="4" />
                <level-list id="spell-list.abjuration.5" level="5" />
                <level-list id="spell-list.abjuration.6" level="6" />
                <level-list id="spell-list.abjuration.7" level="7" />
                <level-list id="spell-list.abjuration.8" level="8" />
                <level-list id="spell-list.abjuration.9" level="9" />
                </spell-list>

                <list-entries list-id="spell-list.abjuration.1">
                <ref refid="spell.shield" />
                </list-entries>

                Which, to some extent, introduces a higher degree of structure and
                reduces the number of lists running around. The <level-list>s (or
                I could even make them <spell-list>s... there're benefits to that)
                are thereby locked within the master list, as they should be, and
                easily isolated so they don't appear when searching for top-level
                lists. It also maintains a little more consistency with the other
                <*-list> types.

                'course, the above is a little annoying for <domain>s, because each
                domain refers to a <spell-list>, and there will (usually) be only
                a single spell for each level in the domain. The SSS books add spells
                to the domain lists, though, so we'll have to support it, and this is an
                easy way of doing so... okay, never mind the complaint. It's not *that*
                much of a hardship.

                > But in general, you seem to have more experience with this stuff than I
                > do, so I'll defer to your decisions. (and keep offering suggestions when
                > they strike me.)

                Well, you've raised some good points and made me think of things that
                I hadn't yet (and perhaps wouldn't have), so it's been beneficial. If
                I seem to ignore what you suggest, don't worry -- I do read and think
                about suggestions, but I have a pretty good idea where I'm going <g>

                Thanks for the feedback.


                Keith
                --
                Keith Davies
                kjdavies@...

                Logan: "I don't think it's a good idea."
                Raven: "The vote is three to one against you -- me, the crystal ball,
                and the little voices in your head."
              • Peter Kahle
                ... Fair enough. ... Um... wouldn t matching on list[@type= weapon ] be more or less the same as matching on weapon-list? I mean, probably a little more
                Message 7 of 13 , Feb 5, 2002
                • 0 Attachment
                  On Tue, Feb 05, 2002 at 12:40:43PM -0800, Keith Davies wrote:
                  >
                  > I'm trying to keep them down, but not to a minimum. When it really
                  > does describe something different (such as a reference to a list rather
                  > than an object) I'd rather have a different element.
                  >

                  Fair enough.

                  > For instance, at one point I was tempted to just make the classification
                  > objects <list>s -- regardless of what they were listing. Makes it nice,
                  > simple, and consistent. All good things. However, the ability to find
                  > lists of certain things (such as of weapons, or spells, and so on) made
                  > that a poor decision, so I decided not to go that way.

                  Um... wouldn't matching on list[@type='weapon'] be more or less the same
                  as matching on weapon-list? I mean, probably a little more processing
                  needed, but functionally pretty mucht he same, right?

                  > I'm still trying to figure out a nice way of doing spell assignments --
                  > getting them into the right list is easy, but specifying the levels in
                  > a useful manner is annoying. The list assignment will work much like
                  > above, and for the same reasons (the assignment is separate from the
                  > reference and classification objects to reduce the impact of adding
                  > new reference or classification objects).
                  >
                  > I could do something like

                  Option 1

                  > <spell-list id="spell-list.abjuration" />
                  > <list-entries list-id="spell-list.abjuration">
                  > <list-ref refid="spells-list.abjuration.0" />
                  > <list-ref refid="spells-list.abjuration.1" />
                  > <list-ref refid="spells-list.abjuration.2" />
                  > <list-ref refid="spells-list.abjuration.3" />
                  > <list-ref refid="spells-list.abjuration.4" />
                  > <list-ref refid="spells-list.abjuration.5" />
                  > <list-ref refid="spells-list.abjuration.6" />
                  > <list-ref refid="spells-list.abjuration.7" />
                  > <list-ref refid="spells-list.abjuration.8" />
                  > <list-ref refid="spells-list.abjuration.9" />
                  > </list-entries>
                  >
                  > <spell-list id="spell-list.abjuration.0" level="0"/>
                  > <list-entries list-id="spell-list.abjuration.0">
                  > <ref />
                  > <ref />
                  > <ref />
                  > </list-entries>
                  >
                  > Which does have the happy effect of breaking the lists down by level as
                  > well... it seems disatisfying, though. I could do

                  Option 2

                  > <spell-list id="spell-list.abjuration" />
                  > <list-entries list-id="spell-list.abjuration">
                  > <spell-ref refid="spell.shield" level="1"/>
                  > <!-- ... -->
                  > </list-entries>
                  >
                  > but that would get *really* old, *really* fast, and doesn't necessarily
                  > gain us anything. I suppose I could do something like

                  Option 3

                  > <spell-list id="spell-list.abjuration">
                  > <level-list id="spell-list.abjuration.0" level="0" />
                  > <level-list id="spell-list.abjuration.1" level="1" />
                  > <level-list id="spell-list.abjuration.2" level="2" />
                  > <level-list id="spell-list.abjuration.3" level="3" />
                  > <level-list id="spell-list.abjuration.4" level="4" />
                  > <level-list id="spell-list.abjuration.5" level="5" />
                  > <level-list id="spell-list.abjuration.6" level="6" />
                  > <level-list id="spell-list.abjuration.7" level="7" />
                  > <level-list id="spell-list.abjuration.8" level="8" />
                  > <level-list id="spell-list.abjuration.9" level="9" />
                  > </spell-list>
                  >
                  > <list-entries list-id="spell-list.abjuration.1">
                  > <ref refid="spell.shield" />
                  > </list-entries>
                  >
                  > Which, to some extent, introduces a higher degree of structure and
                  > reduces the number of lists running around. The <level-list>s (or
                  > I could even make them <spell-list>s... there're benefits to that)
                  > are thereby locked within the master list, as they should be, and
                  > easily isolated so they don't appear when searching for top-level
                  > lists. It also maintains a little more consistency with the other
                  > <*-list> types.
                  >
                  > 'course, the above is a little annoying for <domain>s, because each
                  > domain refers to a <spell-list>, and there will (usually) be only
                  > a single spell for each level in the domain. The SSS books add spells
                  > to the domain lists, though, so we'll have to support it, and this is an
                  > easy way of doing so... okay, never mind the complaint. It's not *that*
                  > much of a hardship.

                  I agree with you that Option 2 is pretty ugly, but by combining it with
                  Option 3, you may be able to simplify domains, and those cases where you
                  would have a very few spells in a level. For example:

                  <spell-list id="spell-list.abjuration" />
                  <spell-list id="spell-list.abjuration.1" />
                  <list-entries list-id="spell-list.abjuration.1">
                  <spell-ref refid="spell.shield" level="1"/>
                  </list-entries>
                  <list-entries list-id="spell-list.abjuration">
                  <spell-list id="spell-list.abjuration.1" />
                  <spell-list id="spell-list.abjuration.2" level="2" />
                  <spell-list id="spell-list.abjuration.3" level="3" />
                  <spell-list id="spell-list.abjuration.4" level="4" />
                  <spell-list id="spell-list.abjuration.5" level="5" />
                  <spell-list id="spell-list.abjuration.6" level="6" />
                  <spell-list id="spell-list.abjuration.7" level="7" />
                  <spell-list id="spell-list.abjuration.8" level="8" />
                  <spell-list id="spell-list.abjuration.9" level="9" />
                  </list-entries>

                  Basically, use spell-list-ref and spell-ref and allow you to define the
                  level for either. if you have a defined level for a spell in a list that
                  you're re-defining the level as you make a composite list, then use the
                  spell-list-ref's level instead of the spell-ref's. It's not perfect, but
                  it seems like it might be the best of the available options. Then again,
                  it might leave too much flexibility, at the expense of the ease of
                  processing. Let me know what you think.

                  > > But in general, you seem to have more experience with this stuff than I
                  > > do, so I'll defer to your decisions. (and keep offering suggestions when
                  > > they strike me.)
                  >
                  > Well, you've raised some good points and made me think of things that
                  > I hadn't yet (and perhaps wouldn't have), so it's been beneficial. If
                  > I seem to ignore what you suggest, don't worry -- I do read and think
                  > about suggestions, but I have a pretty good idea where I'm going <g>

                  Heh.

                  > Thanks for the feedback.

                  No problem.
                  P

                  > Keith
                  > --
                  > Keith Davies
                  > kjdavies@...
                  >
                  > Logan: "I don't think it's a good idea."
                  > Raven: "The vote is three to one against you -- me, the crystal ball,
                  > and the little voices in your head."
                  >
                  >
                  > To unsubscribe from this group, send an email to:
                  > pcgen-xml-unsubscribe@yahoogroups.com
                  >
                  >
                  >
                  > Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/
                  >
                  >

                  --

                  Those who would give up essential Liberty to purchase a little temporary
                  safety, deserve neither Liberty nor safety.
                  -- Ben Franklin

                  || Peter M Kahle Jr || PGP Public Key on Keyservers ||
                  || pkahle@... || http://pops.dyndns.com/~pkahle/ ||
                  ##===============================##======================================##
                • Keith Davies
                  ... It would, actually... and the classification and assignment elements are meant to be fairly simple, as their only purpose is to allow me to group things in
                  Message 8 of 13 , Feb 5, 2002
                  • 0 Attachment
                    Peter Kahle wrote on Tue Feb 5 13:04:04 2002:
                    >
                    > On Tue, Feb 05, 2002 at 12:40:43PM -0800, Keith Davies wrote:
                    > >
                    > > I'm trying to keep them down, but not to a minimum. When it really
                    > > does describe something different (such as a reference to a list rather
                    > > than an object) I'd rather have a different element.
                    > >
                    >
                    > Fair enough.
                    >
                    > > For instance, at one point I was tempted to just make the classification
                    > > objects <list>s -- regardless of what they were listing. Makes it nice,
                    > > simple, and consistent. All good things. However, the ability to find
                    > > lists of certain things (such as of weapons, or spells, and so on) made
                    > > that a poor decision, so I decided not to go that way.
                    >
                    > Um... wouldn't matching on list[@type='weapon'] be more or less the same
                    > as matching on weapon-list? I mean, probably a little more processing
                    > needed, but functionally pretty mucht he same, right?

                    It would, actually... and the classification and assignment elements are
                    meant to be fairly simple, as their only purpose is to allow me to group
                    things in multiple ways. Hmm... it might be nice to have only a single
                    <list> element; this could simplify many things for me.

                    > > I'm still trying to figure out a nice way of doing spell assignments --
                    > > getting them into the right list is easy, but specifying the levels in
                    > > a useful manner is annoying. The list assignment will work much like
                    > > above, and for the same reasons (the assignment is separate from the
                    > > reference and classification objects to reduce the impact of adding
                    > > new reference or classification objects).

                    <bigsnip />

                    > I agree with you that Option 2 is pretty ugly, but by combining it with
                    > Option 3, you may be able to simplify domains, and those cases where you
                    > would have a very few spells in a level. For example:
                    >
                    > <spell-list id="spell-list.abjuration" />
                    > <spell-list id="spell-list.abjuration.1" />
                    > <list-entries list-id="spell-list.abjuration.1">
                    > <spell-ref refid="spell.shield" level="1"/>
                    > </list-entries>
                    > <list-entries list-id="spell-list.abjuration">
                    > <spell-list id="spell-list.abjuration.1" />
                    > <spell-list id="spell-list.abjuration.2" level="2" />
                    > <spell-list id="spell-list.abjuration.3" level="3" />
                    > <spell-list id="spell-list.abjuration.4" level="4" />
                    > <spell-list id="spell-list.abjuration.5" level="5" />
                    > <spell-list id="spell-list.abjuration.6" level="6" />
                    > <spell-list id="spell-list.abjuration.7" level="7" />
                    > <spell-list id="spell-list.abjuration.8" level="8" />
                    > <spell-list id="spell-list.abjuration.9" level="9" />
                    > </list-entries>
                    >
                    > Basically, use spell-list-ref and spell-ref and allow you to define the
                    > level for either. if you have a defined level for a spell in a list that
                    > you're re-defining the level as you make a composite list, then use the
                    > spell-list-ref's level instead of the spell-ref's. It's not perfect, but
                    > it seems like it might be the best of the available options. Then again,
                    > it might leave too much flexibility, at the expense of the ease of
                    > processing. Let me know what you think.

                    I considered allowing the level to be set in either <spell-list> or in
                    <spell-ref>, but I don't like the possible ambiguity that introduces. If
                    someone sets <spell-ref level="2"/> and then does <spell-list level="3"/>,
                    even though the program may act consistently it could confuse the user.

                    The simplest, perhaps, would be to include @level as an attribute of
                    <spell-list>, then have the master <spell-list> contain references to
                    the internal lists... that would be the most consistent with the other
                    classifications. However, given that the level-based sublists really
                    *are* sublists of the master list, and can't be used by other lists,
                    I think it may be best to declare them as such. That makes it easy
                    to identify the top-level <spell-lists>, but still allow assignments
                    to them. At this point, I think

                    <spell-list id="spell-list.abjuration" name="Abjuration">
                    <spell-list id="spell-list.abjuration.0" name="Abjuration 0" level="0" />
                    <spell-list id="spell-list.abjuration.1" name="Abjuration 1" level="1" />
                    <spell-list id="spell-list.abjuration.2" name="Abjuration 2" level="2" />
                    <spell-list id="spell-list.abjuration.3" name="Abjuration 3" level="3" />
                    <spell-list id="spell-list.abjuration.4" name="Abjuration 4" level="4" />
                    </spell-list>

                    may actually be the way to go. I'm not entirely happy about it yet,
                    though.


                    Keith
                    --
                    Keith Davies
                    kjdavies@...

                    Logan: "I don't think it's a good idea."
                    Raven: "The vote is three to one against you -- me, the crystal ball,
                    and the little voices in your head."
                  • giliath01
                    ... useful ... Regretably, that transformation will be rather difficult to do because there is no way to identify the type that a particular list applies to.
                    Message 9 of 13 , Feb 6, 2002
                    • 0 Attachment
                      ><weapon-list id="weapon-list.axes" name="Axes">
                      > <ref refid="weapon.battleaxe"/>
                      > <ref refid="weapon.handaxe"/>
                      > <ref refid="weapon.greataxe"/>
                      ></weapon-list>
                      >
                      >and so on. However, this is (theoretically) beyond the scope of this
                      >project... it's up to the front-end folks to figure out what they
                      >want to do -- we just have to be able to represent the data in a
                      useful
                      >way. I do expect to make recommendations to them, though.

                      Regretably, that transformation will be rather difficult to do
                      because there is no way to identify the type that a particular list
                      applies to. If you have just a generic list-entries assignment,
                      without inspection into the actual data that the reference ids have
                      inside the gui group will not be able to determine that the list is a
                      <weapon-list>. I am not sure, but I don't think the XSLT
                      transformation engines can do that type of manipulation without a lot
                      of work.

                      Now you could add some outer wrappers to get types of information
                      together like this:

                      <races>
                      <specifications />
                      <classifications />
                      <assignments />
                      </races>

                      This would give it a more explicit grouping and make it easier to do
                      an XSLT transformation like you described above. If you don't have
                      an explicit mapping that allows you to group all of the <list-
                      entries> that are races together you have no way of knowing that a
                      list contains races without doing inspection into what it contains.

                      >I considered something like this once, for another schema. Frankly,
                      >it was a pain in the ass to use. <ref> (or <entry>, above) tend to
                      >be fairly obvious in context. That it is a reference to a race can
                      >be inferred by the ID (<entry refid="race.elf"/>, f'rex) and context.
                      >Having to use specifical <*-ref> types got to be annoying, especially
                      >when they're all doing the same thing. I could see some small gain
                      >in that it describes the data in higher detail, but -- at this
                      point --
                      >I don't think it's gains enough to be worth the trouble.

                      While I understand how it is a pain in the ass to use <ref> entries,
                      this approach give a more explicit definition for both the XML editor
                      and more importantly for the java developer doing the data loading.
                      When creating lists inside the java you want to be able to explicitly
                      know that every reference object inside this list is of an
                      appropriate type, but there is no typing at all on the lists.

                      Both of these suggestions come back to the same problem. If we
                      genericize the data too much, it is much more difficult to display a
                      list of races. With the assignments you are proposing, without
                      hardcoding IDs into the java, how do you identify that a particular
                      list is a list of races? what is a list of classes? The java
                      developer that is loading this data shouldn't have to do
                      validation to make sure that lists contain appropriate groups, that
                      should be taken care of in the XML definition.

                      ~David
                    Your message has been successfully submitted and would be delivered to recipients shortly.