[rfc-i] Request for information - other SDO's and style guides

Bjoern Hoehrmann derhoermi at gmx.net
Thu Apr 11 13:58:29 PDT 2013


* Heather Flanagan (RFC Series Editor) wrote:
>While I have the editorial style guides for several SDO's (IEEE, W3C,
>ITU, ISO) that provide guidance on language and grammar, none of those
>style manuals provide guidance for the HTML, PDF, ODT, DOC, or whatever
>format(s) they use to publish their standards.  The closest is the W3C
>which points authors to a separate document on XML, XMLspec, and XSLT. 
>I have a suspicion that other standards bodies either have this kind of
>information purely for their editorial staff or they accept whatever is
>provided by the authors with no further cleanup.

The W3C requires use of HTML for the normative publication and that HTML
has to, essentially, pass their http://validator.w3.org/ validator, and
there are a few additional requirements regarding boilerplate text, the
style sheet to use, and some document meta data, collectively the rules
are under http://www.w3.org/2005/07/pubrules publically available. There
aren't really rules beyond that, but being the W3C, incorrect or other-
wise poor use of HTML markup and whatever else is used has little chance
to make it through their process.

They do have a separate track for http://www.w3.org/Submission/ various
non-standards-track submissions that receive little review prior to pub-
lication, where need for cleanup has been an issue in the past, but as I
understand it, running http://tidy.sourceforge.net/ over such input does
tend to address most problems. I also note that it's rare these days to
see problems common with ordinary word processors, like people manually
indenting text or lists with white space, rather than using the features
of the word processor for them with any kind of HTML document.

For W3C documents, people mostly tend to use various pre-processors any-
way to take care of common problems like automatic section numbering or
ToC generation, linking, and so on, XMLSpec as you mention it above was
one such document format with an associated toolchain to this end, so it
tends to be difficult to introduce anything that requires cleanup or any
particular guidance. A notable difference though is that there has never
been much of an expectation that there is editorial consistency among
technical reports from different groups, the way that might be expected
of the RFC editor.

A simple example for that would be the use of code snippets which could
be marked up like

  <pre>
  int plus(int a, int b) {
    return a + b;
  }
  </pre>

or perhaps like

  <pre><code>
  int plus(int a, int b) {
    return a + b;
  }
  </code></pre>

to indicate more clearly that the contents is computer code. If the RFC
editor sometimes produces one, and sometimes the other, that might seem
disorderly and lead to complaints, while at the W3C people would leave
this more readily to individual editors who are essentially responsible
for producing the final form of the documents without any editing by the
W3C staff as such.
-- 
Björn Höhrmann · mailto:bjoern at hoehrmann.de · http://bjoern.hoehrmann.de
Am Badedeich 7 · Telefon: +49(0)160/4415681 · http://www.bjoernsworld.de
25899 Dagebüll · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/ 


More information about the rfc-interest mailing list