Skip to content

ISODoc: Text

Jump to bottom
Ronald Tse edited this page Jan 26, 2018 · 49 revisions
text 
TextElement =
  text | em | eref | strong | stem | sub | sup | tt | xref | br | hyperlink


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

eref =
  element eref {
    attribute normative { xs:boolean },
    # 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
}

hyperlink =
  element link {
    attribute targetUri {xs:anyUri},
    text
}

# 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? { xs:anyUri },
    # 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" ) }
}

stem =
  element stem {
    attribute type { "MathML" },
    text
}

calloutlist =
  element calloutlist {
    annotation+
}

annotation =
  element annotation { paragraph }

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. (Updated) Moved type to ReferenceElement.

  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.

    2. I still do not understand why we are giving the linked TextElement. So in "This is a codeframe (ISO 613 section 31) <eref citation="ISO 613, section 31" normative=true>Text</eref>, what is the linkedElement? The paragraph containing the eref? The text "This is a codeframe"? Give me an example of this. If this is the text element that the citation occurs next to, it is not needed at all in text markup, just like it wasn’t for footnotes.

    3. In the example of: This is a <eref citation="citation_123" cite-as="(ISO 613, section 31)" normative=true>codeframe Text</eref><citation id="citation_123" bibitem="bibitem_1234" biblocality-type="section" biblocality-ref="31"/><bibitem id="bibitem_1234" code=613 name="ISO 613"/>:

      1. eref.text = "codeframe Text"

      2. eref.citeAs = "(ISO 613, section 31)"

      3. eref.citation = <Citation id="citation_123" bibitem="bibitem_1234" biblocality=<BibLocality type="section" ref="31">

      4. eref.citation.bibItem = <BibItem id="bibitem_1234" code=613 name="ISO 613">

  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.)

    1. Let’s see how we can achieve this then.

  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?

    2. (Nick can you confirm?)

  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?

    2. (Nick can you confirm?)

  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

    2. No, it’s still there. In fact, given DefinitionElement, the terms should not be there at all.

    3. (Updated; fixed — or should this be Paragraph or some Block, since ISO allows Figures and Formulas?)

  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.

    1. Fixed.

  21. You’re missing br

    1. Fixed.

  22. TextAlignment: add "justified"

    1. Fixed, added left/right 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.

    1. On second thought, a "reviewer note" or "normal note" should not be limited to apply on a ParagraphBlock only…​ I wonder if we should create a "Annotation" object that can refer to the beginning of a range and end of range to indicate where the annotation applies?

  24. CalloutList is now missing.

    1. What’s the difference between CalloutList and CalloutAnnotation?

  25. anchor needs to be replaced with id throughout

    1. Can you tell me which anchors are confusing with id?

  26. List does not need +listitem, it is now in UnorderedList.

    1. Fixed.

  27. Figure/Source: should be replaced with Figure/Image

    1. I thought Figure can contain many things other than just an image? How about ASCII Art?

  28. ol/type: add "arabic" for numbers. Also upper Roman and upper Alpha

    1. Fixed.

Clone this wiki locally