- Notifications
You must be signed in to change notification settings - Fork14
A set of custom HTML elements to make writing well-formatted C++ papers and ISO documents easier.
License
cplusplus/html-doc-framework
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
This is aPolymer-based HTML framework forwriting ISO C++ documents and papers. To use it for your document, you should
Install this package by running
bower install cplusplus/html-doc-frameworkin the root directory of your document.Import this package into your main HTML file by adding two lines inside the
<head>element:<scriptsrc="bower_components/webcomponentsjs/webcomponents.js"></script><linkrel="import"href="bower_components/cxx-html-doc-framework/framework.html"/>
Run an HTTP server (e.g.
python3 -m http.serverorhttp-server) in the directory of your main HTML file, and preview through that instead of afile:///URL.
I recommend thePrince rendering engine for converting your HTML file to PDF. It has significantly better support for page-related features than any browser as of 2014.
Before I can accept a contribution to this project, you'll need to sign theContributor License Agreement athttps://developers.google.com/open-source/cla/individual.
Some of these elements define acheckInvariants() method, so you can run:
document.querySelectorAll('*').array().forEach( function(node){ if (node.checkInvariants) node.checkInvariants(); });to see if you've gotten anything wrong.
This one isn't really C++-specific: it allows partitioning a main documentinto multiple pieces.other.html's body will be copied in place of the<cxx-include> element.
These automatically number clauses and sections, fill intable-of-contents data, and allow cross-linking.<cxx-clause> is fortop-level sections, while<cxx-section> can be nested arbitrarily.The title of the section is given in a nested<h1> element.Theid attribute is used for cross-linking.
Wraps the title page of an ISO document. The title page takes astage attribute whose value can bedraft or (once I implementthem)CD,DTS,TS, etc. The title page recognizes severalnested elements that describe the document.
The ISO project number for this TS or IS. Find this onhttps://isocpp.org/std/status.
The D or N number for the document.
The publication date of the document in ISO (YYYY-MM-DD) format.
The N number of the previous version of the document.
A paragraph describing the editor of the document. Use<br> toseparate lines.
Generates a table of contents based on the<cxx-section> structure.
Open the document using Polymer's shadow-dom polyfill (add?shadow=polyfill to the URL) and then click this button to generatea standalone version of the document, that doesn't rely on any customelements, scripts, or external CSS. The result of this transformationis what actually gets published in the C++ committee mailings.
It's tested back to IE 8 and should degrade fairly gracefully in evenolder browsers.
Numbers the terms in the<dl> with the parent<cxx-section>'s sectionnumber, and formats and links theid.
An editor's note that won't appear in the final published document.This is formatted as a separate box on the side of the document,unless it's marked with, in which case it's formatted as a normal paragraph in a box.
Must contain an email address as text, and wraps it into anappropriatemailto: link.
Introduces a soft line-break inside an otherwise-nowrap context. This works inFirefox and Prince, where fails, in addition to other browsers.
Describes a C++ library function. Several nested elements helpdescribe the signatures and semantics of a function.
Use one of these for each related function signature that can bedescribed by a single set of attributes.
<cxx-requires>,<cxx-effects>,<cxx-synchronization>,<cxx-postconditions>,<cxx-returns>,<cxx-throws>,<cxx-exception-safety>,<cxx-remarks>,<cxx-error-conditions>, and<cxx-notes>
Each of these elements represents one attribute from [structure.specifications]p3 (except for<cxx-exception-safety>).
Wraps non-normative text inside a paragraph.
Links to a section in the current document, whoseid is given by theto attribute on the<cxx-ref>. References are displayed like"(1.2.3)", unless theinsynopsis attribute is also present, inwhich case the reference is displayed as a C++ comment, "// 1.2.3, title of referenced section".
Adds a "Table # —" prefix to the table<caption>.
This guide is intended to produce results compatible with the main C++standard, which is written in LaTeX.
Write semantic markup according tohttp://developers.whatwg.org/.
Generally use<code> rather than<samp>,<kbd>,<tt> or othermonospacing elements.<samp> could be useful for sample compilererror messages. Don't use<kbd> for code a user might enter: that'sjust<code>.
Use<em> for emphasis and<i> for text in another "voice", likecomments and technical terms.<dfn> is good for the defininginstance 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 allvariables, including function parameters, and only calling outmeta-variables used in documentation. I'm leaning toward onlymeta-variables, since marking up parameters requires a huge number oftags, which make it harder to read the source, and there's not muchreason to italicize normal variables. Most meta-variables will end upmarked up as<code><var>meta-variable</var></code>.
Very little text is bold, either with<strong> or<b>.
In CSS, avoid the CSScontent property because it doesn't copy/paste well in many browsers.Use a custom element with text in the<template> instead.Shadow DOM (what's generated from the template) also doesn't copy/paste well, but that's improving,and the polyfill can produce non-Shadow DOM, which<cxx-publish> can fix into plain HTML.
About
A set of custom HTML elements to make writing well-formatted C++ papers and ISO documents easier.
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Contributors4
Uh oh!
There was an error while loading.Please reload this page.