Unify formatting (function calls, code blocks, quotes) in the specification

[ChristianGruen]

Todos (2023-05-18):

• [x] Initial cleanup of fn: prefixes → #475
• [x] Remove more fn: prefixes → #509
  • fn: prefixes in examples that raise an error.
  • fn: prefixes in eg code blocks
  • other documents: expressions.xml, query-examples.xml, …
• [x] Render false, true, NaN, INF, +INF as code → #510
• [x] Render string values as code and use quotes: "yes", "true", "0" → #511
• [x] Omit quotes for single characters: \b, \f, … → #511
• [x] Rewrite simple to typographic quotes → #511

---

Inspired by https://github.com/qt4cg/qtspecs/pull/454#issuecomment-1534633089 ff.

The syntax of the examples in the XQFO specification is inconsistent. Sometimes, functions in the standard function namespace have an fn prefix…

• fn:fold-right(1 to 5, "", fn:concat(?, ".", ?))
• fn:substring("motor car", 6)

…sometimes they don’t…

• data(123)
• concat("http://www.example.com/", encode-for-uri("~bébé"))

…sometimes it’s both:

• fn:fold-right(1 to 5, "$zero", concat("$f(", ?, ", ", ?, ")"))
• fn:concat(01, 02, 03, 04, true())
• fn:tokenize(fn:unparsed-text($href), '\r\n|\r|\n')[not(position()=last() and .='')]

Should we drop or keep the prefix – or doesn’t it really matter? If there’s interest, I can create a PR (I’d tend to drop the prefixes).

In addition, there doesn’t seem to be a consistent rule for representing booleans. We have:

Syntax	Comment
…returns false	mostly used in the rules (seems appropriate to me)
…returns false	used in the rules; maybe we should use replace it with the first syntax?
…the result is fn:false()	used in the rules; maybe we should use replace it with the first syntax?
…returns false()	mostly used in the examples (seems appropriate to me)

[michaelhkay]

I'm in favour of dropping the fn: prefix from examples.

Note that in appropriately marked-up examples the code must be executable and testable, hence false() as the expected result. (Which reminds me that it's time we re-ran the generation of test cases - ideally integrating it into the build).

[ChristianGruen]

Here are some examples of how the true keyword/value is currently rendered:

The best solution could be to always wrap boolean values in <code> elements (and keep false() and true() for executable code).

[benibela]

But there should be examples for every possible syntax, so people can learn them all

[michaelhkay]

I suggest that we should consistently render the values true, false, and NaN in code font, even though they are not XPath literals. We should also render xs:string values as, for example "yes", with both the content and the quotes in code font. It's possible to find inconsistencies by using the XPath expression

//text()[not(parent::code|parent::rhs|parent::eg)][contains(.,'"')]

against a file such as shared-assembled.xml; no doubt this can be made more precise.

In a context that expects an XPath expression, of course (like fos:result) we need to write true() and false().

We're also inconsistent about whether we use code font (and quotes) around namespace URIs. Perhaps these should be marked up as <code role="namespace">http://....</code> and then we can control it in the CSS...

[ChristianGruen]

@michaelhkay Sounds good. I'll wait until the current PR is merged to minimize conflicts.

[ChristianGruen]

I suggest that we should consistently render the values true, false, and NaN in code font, even though they are not XPath literals.

+1

We should also render xs:string values as, for example "yes", with both the content and the quotes in code font. It's possible to find inconsistencies by using the XPath expression

Sounds reasonable. For now, I’ll probably limit the cleanups to cases that can safely be automatized. Sanitizing all quoted strings feels like a tedious task, as they are often used in full text. Examples:

• Other recommendations ("host languages")…
• such as "the second argument" as…
• This specification spells "codepoint" as one word…
• for concepts such as "Base URI"…
• the phrase "an error is raised" is used…

However, I noticed that typographic quotation marks (201C/201D) are repeatedly used, even for code:

• In other words, appending “(d e)” to “(a b c)” produces a sequence of length 5: “(a b c d e)”.
• the lexical <code>xs:dateTime</code> representation “<code>2003-01-02T11:30:00-05:00</code>”
• replaces all occurrences of plus (“<code>+</code>”) with spaces

If no one objects, I’ll replace those with standard quotes (once again, it feels like too much effort to apply them consistently for full text without making things worse). Next, quotes around <code> elements should probably be moved inside the value.

against a file such as shared-assembled.xml; no doubt this can be made more precise.

As I’m operating on the raw documents: Which files are contained in the assembled file?

[ndw]

Is this fully resolved by #475 or only partially resolved? If it's fully resolved, please close it.

[ChristianGruen]

@ndw At least one more PR will follow.

[ChristianGruen]

I wanted to tackle this today, but I’ll wait until we’ve merged most open pull requests.

To be cleaned up:

• fn: prefixes in examples that raise an error.
• fn: prefixes in eg code blocks
• other documents: expressions.xml, query-examples.xml, …

[michaelhkay]

Changing typographical apostrophes to ASCII apostrophes seems like a retrograde step. Just saying.

[ndw]

Yes, but I think @ChristianGruen was making the quite reasonable observation that the only places using typographical quotes were the bits I'd written recently (because my damned editor is smart enough to do them for me in 2023, just like it was in 2003).

I don't know that inconsistency in this regard is in any practical way a bad thing, but I appreciate consistency for consistency's sake.

I'd be tempted to fix this, globally, except that if most authors aren't going to use them, then every edit is likely to re-introduce straight quotes and that's just going to be endlessly annoying.

[michaelhkay]

Well, the XSLT spec uses typographical quotes and apostrophes pretty systematically (and it was done by hand, because you don't want them in code sections). I hope no-one is going to undo that.

[ndw]

Ah. Good job. Then the narrower observation was that in F&O, they are all straight quotes. I'm in favor of a commitment to use proper typographic quotes in prose, if all the other editors are willing to sign on.

[ChristianGruen]

Any decision is fine for me. Indeed, I mostly thought about consistency as it personally puzzles me when both simple and typographic quotes are used in the same text (in German texts, you sometimes find mixtures of "/", „/“ and »/«) …but that’s what some people call “Kommafaschismus”, so chances are good that most people wouldn’t notice it.

I think, however, we should avoid typographic quotes for code. For example, in XQuery and XPath Data Model 4.0 there is…

• “2003-01-02T11:30:00-05:00”
• “-0”

…while simple quotes are often used for prose:

• henceforth "data model"
• "the state of having no value"
• …

[ndw]

Any typographic quotes in code are a straight-up error, except in exceptional circumstances. (E.g. where the point of the code is to demonstrate a typographic quote or something.)

[ChristianGruen]

We should also render xs:string values as, for example "yes", with both the content and the quotes in code font. It's possible to find inconsistencies by using the XPath expression

If we want to be consistent, I wonder if it’s not better to render it as yes, unless the string value itself contains quotes (codepoints-to-string(0x22) → "). Related: https://github.com/qt4cg/qtspecs/pull/502#issuecomment-1549242269

[michaelhkay]

It's very hard to get this right. In my XSLT book I used «true» to refer to a value in the value space of xs:boolean, and «"true"» to refer to a 6-character string literal including its delimiting quotation marks, and it's certainly handy to have some extra symbols in the toolbag. But here's a paragraph from the XSLT spec that I think reflects good practice:

One of the strings "yes", "true", or "1" to indicate the value true, or one of the strings "no", "false", or "0" to indicate the value false. Note: the values are synonyms; where this specification uses a phrase such as “If required='yes' is specified ...” this is to be interpreted as meaning “If the attribute named required is present, and has the value yes, true, or 1 (after stripping leading and trailing whitespace) ...”.

Note: code font with no quotes for values or fragments of code; code font with ASCII quotes where we are talking about lexical representations of values; typographical quotes for quoted text.

[ChristianGruen]

Thanks, both the description and the example is helpful. Regarding single characters, I assume the best solution is to omit quotes? Similar to…

• https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-xml-to-json:
  …tab, or solidus is replaced by \", \b, \f, \n, \r, \t, or \/ respectively;
• https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func-replace:
  a literal $ character within the replacement string must be written as \$, and a literal \ character must be written as \\.

Here’s one example where it may need to be fixed:

• https://qt4cg.org/specifications/xpath-functions-40/Overview.html#defining-decimal-format:
  Defines the character used to represent the decimal point (typically ".") → (typically .)

I won’t go into more detail… It’s really just trifles what’s left.