fundamentals-ts
The draft C++ Library Fundamentals Technical Specification.
The draft can be viewed online at: https://cplusplus.github.io/fundamentals-ts/
This TS is written using a set of custom HTML elements based on the Polymer framework.
Style guide
This guide is intended to produce results compatible with the main C++ standard, which is written in LaTeX.
Look for applicable <cxx-*>
elements,
and write semantic markup according to http://developers.whatwg.org/.
Generally use <code>
rather than <samp>
, <kbd>
, <tt>
or other
monospacing elements. <samp>
could be useful for sample compiler
error messages. Don't use <kbd>
for code a user might enter: that's
just <code>
.
Use <em>
for emphasis and <i>
for text in another "voice", like
comments and technical terms. <dfn>
is good for the defining
instance of a term, but not for subsequent uses. I may add a
<cxx-term>
element to call out uses of technical terms specifically,
which will enable automatic cross-linking and indexing.
Use <var>
for variables. There's tension between using it for all
variables, including function parameters, and only calling out
meta-variables used in documentation. I'm leaning toward only
meta-variables, since marking up parameters requires a huge number of
tags, which make it harder to read the source, and there's not much
reason to italicize normal variables. Most meta-variables will end up
marked up as <code><var>meta-variable</var></code>
.
Very little text is bold, either with <strong>
or <b>
.
Any repeated markup structure should be abstracted out into a custom element in the https://github.com/cplusplus/html-doc-framework project.
Namespace formatting
Namespace contents are indented by 2 spaces, with one blank line between the namespace open and the first line of the contents. Multiple namespaces can be opened at the same indentation level, like:
namespace std {
namespace experimental {
class contents{};
} // namespace experimental
} // namespace std
Namespaces are only shown in header synopses, not around class or function definitions.