Skip to content

ISODoc: Text

Jump to bottom
Nick Nicholas edited this page Jan 25, 2018 · 49 revisions
paragraph
text 
TextElement =
  text | em | eref | strong | stem | sub | sup | tt | xref | br

paragraph =
  element p { ParagraphType }

ParagraphType =
    attribute alignment? ( { "left" | "right" | "center" } ),
   ( TextElement | reviewer_comment )*
   # the definition lists reviewer_comment separately, but it is already a subclass of TextElement



paragraph_with_footnote =
  element p {
    attribute alignment? ( { "left" | "right" | "center" } ),
   ( TextElement | fn | reviewer_comment )*
   # the definition lists reviewer_comment separately, but it is already a subclass of TextElement
}

fn =
  element fn {
    attribute type? ( "footnote" | "inline" ),
    # no, this does not belong here, it belongs to ExternalReferenceElement
    paragraph+
}

em = element em { text }
strong = element strong { text }
sub = element sub { text }
sup = element sup { text }

reviewer_comment =
  element reviewer_comment {
  attribute reviewer? { text },
  attribute date { text },
  paragraph+
}

eref =
  element eref {
    attribute normative { text },
    # surely unnecessary if we have separate normative and informative reference sections;
    # at minimum, this attribute should be optional
    attribute citation { text },
    attribute target { text },
    # why are both needed? is target just a url?
    # if so, ExternalRef and Hyperlink should be encoded as separate elements
    # bibliographic xrefs can have urls some times (in RFC XML), but that's an abuse:
    # the url belongs inside the bibliographic reference, not the citation
    text
}
# Asciidoc conflates ExternalRef and CrossRef, but keeps Hyperlink separate.
# You are conflating, I think, ExternalRef and Hyperlink, which is misleading.
#
# We have not included the bibLocality in the converter yet, but that can be done, presumably in markup
# within the <<>> tag.
#
# eref, xref are *not* anchored elements; they do not have their own ids, they link to ids as targets.
# Moreover, they do not have bodies including arbitrary text elements (including other anchored elements).
#
# As far as I can tell, AnchoredElement.body replaces TextElement.content; that's consistent with the
# rule for instantiation I came up with

target = element target { text }

iso_ref =
  element iso_ref {
    attribute normative { text },
    # surely unnecessary if we have separate normative and informative reference sections;
    # at minimum, this attribute should be optional
    # attribute citation { text },
    attribute target { text },
    # why are both needed? is target just a url?
    # if so, eref and xref should be encoded as separate elements
    # bibliographic xrefs can have urls some times (in RFC XML), but that's an abuse:
    # the url belongs inside the bibliographic reference, not the citation
    attribute isocode { text },
    attribute isopublisher {text }
    # isocode + isopublisher replace citation; the UML is misleading
    text
}

xref =
  element xref {
     attribute targetAnchor { text }
     text
}

image =
  element image {
    attribute anchor { text },
    attribute source? { text },
    # surprised you're not making the type of this a URI; relative file paths are still arguably URIs
    attribute imageType { ("SVG" | "JPEG" | "GIF" | "PNG" | "PDF" ) }
    # why supply this?
}
# images do not have textual content or bodies -- unless you want to model alt text that way

formula =
  element formula {
    attribute anchor { text },
    # anchor redundantly specified on Formula
    attribute type { "MathML" },
    stem, dl?
}
# There's a confusion here: formula is the block, stem is the inline element. So Formula
# needs to move to the block model, and stem needs to replace it in the text model

stem =
  element stem { text }

calloutlist =
  element calloutlist {
    annotation+
}

annotation =
  element annotation { paragraph_with_footnote+ }
# callouts the Asciidoc way are single paragraphs, and have no footnotes; we could allow
# this more liberal definition, but asciidoc will not deal with it

ul =
  element ul { li+ }

li =
  element li { paragraph_with_footnote+ }

ol =
  element ol {
     attribute type { "roman" | "alphabet" },
     li+
}

dl =
  element dl {
    (dt, dd)+
}

dt =
  element dt { string }
# Do not use the type Term for dt, which is the quite elaborate Terms & Definitions structure;
# this is TextElement

dd =
  element dd { paragraph_with_footnote+ }

Items for discussion (threaded: identify by number)

  1. paragraph/reviewer_comment, paragraph_with_footnote/reviewer_comment: the UML the definition lists reviewer_comment separately, but it is already a subclass of TextElement, so it is redundant

    1. Moved "notes" to BasicBlock so you can actually comment on a Block.

  2. fn@type: no, this does not belong here, it belongs to ExternalReferenceElement

    1. (TODO)

  3. fn/paragraph: obligation is 1..* not 0..*

    1. Fixed.

  4. fn/associated_element: I don’t understand why associatedElement is needed at all; the associated element is the element it succeeds. This is not a conceptual model, but a logical model.

    1. Removed.

  5. reviewer_comment/content: arguably it is paragraph+

    1. Fixed

  6. eref@normative: surely unnecessary if we have separate normative and informative reference sections; at minimum, this attribute should be optional

    1. Fixed

  7. eref@target: why are both citation and target needed? is target just a url? If so, ExternalRef and Hyperlink should be encoded as separate elements. Bibliographic xrefs can have urls some times (in RFC XML), but that’s an abuse: the url belongs inside the bibliographic reference, not the citation

    1. target was meant to be the TextElement that is linked to the Citation. No change here.

  8. eref: Asciidoc conflates ExternalRef and CrossRef, but keeps Hyperlink separate. You are conflating, I think, ExternalRef and Hyperlink, which is misleading.

    1. Resolved.

  9. eref@citation: We have not included the bibLocality in the converter yet, but that can be done, presumably in markup within the <<>> tag. (It would likely have to be modelled as a separate element within eref though.)

  10. eref, xref: eref, xref are not anchored elements; they do not have their own ids, they link to ids as targets. Moreover, they do not have bodies including arbitrary text elements (including other anchored elements).

    1. Fixed, I think?

  11. eref/content: As far as I can tell, AnchoredElement.body replaces TextElement.content; that’s consistent with the rule for instantiation I came up with

    1. Fixed

  12. iso_ref/isocode: isocode + isopublisher replace eref/citation; the UML is misleading

    1. Fixed

  13. image@source: surprised you’re not making the type of this a URI; relative file paths are still arguably URIs

    1. Fixed

  14. image@imageType: why supply this?

    1. In case MIME type detection fails?

  15. image/content: images do not have textual content or bodies — unless you want to model alt text that way. UML is misleading.

    1. Fixed

  16. formula@anchor: anchor redundantly specified on Formula, it is already inherited from parent

    1. Fixed

  17. formula: There’s a confusion here: formula is the block, stem is the inline element. So Formula needs to move to the block model, and stem needs to replace it in the text model

    1. Fixed

  18. annotation: callouts the Asciidoc way are single paragraphs, and have no footnotes; we could allow this more liberal definition, but asciidoc will not deal with it

    1. Fixed

  19. dt: Do not use the type Term for dt, which is the quite elaborate Terms & Definitions structure; this is TextElement

    1. Fixed

  20. InlineFormulas should go with TextElement, not AnchoredElement: they don’t have anchors, because they are inline, and they can occur where any other TextElement can.

  21. You’re missing br

  22. TextAlignment: add "justified"

  23. paragraph/note: make it review_note, normal notes may still make it to paragraphs in implementations, and don’t want to conflate reviewer notes and normal notes anyway.

Clone this wiki locally