ISODoc: Text

TextElement =
  text | em | eref | strong | stem | sub | sup | tt |
  strike | smallcap | xref | br | hyperlink | hr | pagebreak


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

br = element br { empty }
hr = element hr { empty }
pagebreak = element pagebreak { empty }

ReferenceFormat = ( "external" | "inline" | "footnote" | "callout" )

eref =
  element eref {
    attribute normative { xs:boolean }?,
    attribute citeas { text },
    attribute type { ReferenceFormat },
    CitationType,
    text
}

hyperlink =
  element link {
    attribute target { xs:anyUri },
    attribute type { ReferenceFormat },
    text
}

xref =
  element xref {
     attribute target { xsd:IDREF },
     attribute type { ReferenceFormat },
     text
}

fn =
  element fn {
    attribute reference { text },
    paragraph+
}
# This is xref with fixed @type="footnote", and @target built in as paragraph+
# @reference replaces ReferenceElement/text
# so <fn reference="2"><p>This is a footnote</p></fn>
# corresponds to <xref type="footnote" target="fn2">2</xref> <p id="fn2">This is a footnote</p>

callout =
  element callout {
    attribute target { xsd:IDREF },
    text
  }

# This is xref with fixed @type="callout"; the target by convention is in an annotation in the same source code snippet
# so <callout target="xyz">1</callout>
# corresponds to <xref type="callout" target="xyz">1</xref>

image =
  element image {
    attribute id { xsd:ID },
    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" | "AsciiML" },
    text
}

annotation =
  element annotation {
    attribute id { xsd:ID },
    paragraph
}

ul =
  element ul {
    attribute id { xsd:ID },
    li+
}

li =
  element li { paragraph_with_footnote+ }

ol =
  element ol {
    attribute id { xsd:ID },
     attribute type { "roman" | "alphabet" | "arabic" | "roman_upper", "alphabet_upper" },
     li+
}

dl =
  element dl {
    attribute id { xsd:ID },
    (dt, dd)+
}

dt =
  element dt { TextElement }

dd =
  element dd { paragraph_with_footnote* }

Items for discussion (threaded: identify by number)

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.
fn@type: no, this does not belong here, it belongs to ExternalReferenceElement
1. (Updated) Moved type to ReferenceElement.
fn/paragraph: obligation is 1..* not 0..*
1. Fixed.
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.
reviewer_comment/content: arguably it is paragraph+
1. Fixed
eref@normative: surely unnecessary if we have separate normative and informative reference sections; at minimum, this attribute should be optional
1. Fixed
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">
eref: Asciidoc conflates ExternalRef and CrossRef, but keeps Hyperlink separate. You are conflating, I think, ExternalRef and Hyperlink, which is misleading.
1. Resolved.
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.
2. Will be future ticket.
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?)
3. No, reference elements still are subclasses of textElementWithAnchor; they should be separate subclasses of textElement, they have targets, not anchors
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
iso_ref/isocode: isocode + isopublisher replace eref/citation; the UML is misleading
1. Fixed
image@source: surprised you’re not making the type of this a URI; relative file paths are still arguably URIs
1. Fixed
image@imageType: why supply this?
1. In case MIME type detection fails?
2. (Nick can you confirm?)
3. I am now doing MIME detection, but sure.
image/content: images do not have textual content or bodies — unless you want to model alt text that way. UML is misleading.
1. Fixed
formula@anchor: anchor redundantly specified on Formula, it is already inherited from parent
1. Fixed
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
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
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?)
4. You’re right, basicblock+.
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.
You’re missing br
1. Fixed.
TextAlignment: add "justified"
1. Fixed, added left/right justified
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?
2. Please ticket me to research that; Word does it by inserting bookmarks to delimit start and end of range, and that might be the expedient thing to do --- AnchoredElement instances with no textual content. (corresponds to <a name="">)
3. Done, updated ReviewComment to have appliedFrom and appliedTo, both AnchoredElements.
CalloutList is now missing.
1. What’s the difference between CalloutList and CalloutAnnotation?
2. None, eliminating callout list
anchor needs to be replaced with id throughout
1. Can you tell me which anchors are confusing with id?
2. … all of them? Is anchor actually different from id? I’m currently seeing ids on sections and anchors on blocks, but they are doing the same thing.
3. No more "anchor" now.
List does not need +listitem, it is now in UnorderedList.
1. Fixed.
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?
2. You’re right, they can. But they also need to contain images. Add image alongside source.
3. Fixed.
ol/type: add "arabic" for numbers. Also upper Roman and upper Alpha
1. Fixed.
The link text of eref, xref, link is in fact the inherited content of the TextElement superclass, so I do not need to add a linkText attribute: that’s just <link>link text</link>, <xref>link text</xref>
1. Addressed.
ReferenceElement/type is external/inline. ISO had inline vs footnote; why is this different? You don;'t supply it in your example; is it optional?
1. Addressed and generalized.
Change the ref types to reflect your example:

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"/>:

eref.text = "codeframe Text"

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

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

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

eref contains: citation (string) which points to citation (the UML hints that it contains a citation); and cite-as attribute, which you have not named.
Addressed.
1. reference to ISOelement is redundant
Addressed.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ISODoc: Text

Clone this wiki locally