Search

Lesson style guide

Note: If you run across other tags used in articles not defined here, please add them.

WordPress Gotchas

WordPress will try to render all text as HTML, so < gets treated as an HTML open tag symbol rather than a < literal. If you need to display an < outside of the [code] tag, use &lt; instead.

If you need to display a [ character without it being interpreted by a macro, use &#91;

General formatting

  • One or two spaces after a period doesn’t matter.
  • Separate paragraphs with a blank line
  • Prefer full programs to snippets. It makes it easier for readers to copy examples into a compiler and play with them.

HTML tables should be wrapped in the following div: <div class="cpp-table-wrapper">Table here</div>
If you have a table or code example near the top of the lesson, the formatting can be awkward. Use the following to push subsequent content below the image: <p style="clear: both"></p> <!-- break around image -->

Inline Tags

These tags can be placed in the middle of text.

Define a new term. Should also be added to the site index (here)

[def]term[/def]

Emphasizes some text

<em>text</em>

Useful if you want to embed a line of code in a sentence without causing line breaks around it. Does not syntax highlight. Should be used for identifiers, file names, keywords, expressions, and C++ terms that are hard to parse in a sentence (e.g. when using an <code>if statement</code>…). e.g. namespace should be coded if the term is being used as a keyword, but not if it’s being used as a concept.

<code>Embedded code or text</code>

Link to another lesson. You can find lesson indices by editing the articles and looking in the URL.

[link id=”lesson_index”]

Links to another lesson but removes the preceding lesson number. Only used on the front page of the site, where the lesson numbers are shown in the preceding column.

[link id=”lesson_index” titleonly]

Arbitrary link to another location

<a href=”URL”>descriptive text</a>

Block tags

These tags should always go on their own line and have specific formatting requirements.

[code]
C++ code to be syntax highlighted here
[/code]

<pre>
Text displayed literally. Used for showing the results of sample programs.
</pre>

[section]Title[/section]
[section top]Title[/section]

Defines a new section. Section titles should start with a capital letter and otherwise use lower case.

[section subtag]

Subtags supported:
chaptersummary -- Used in the summary chapters only
summary -- used at the bottom of some chapters to define
conclusion -- used at the bottom of some chapters to conclude the article. Used inconsistently.
quiz -- used for quiz sections

[note subtag]

Note here
[/note]

Note the required blank line after the opening tag. This is required for formatting purposes.

Subtags supported:
optional -- optional reading
aside -- an interesting factoid not strictly relevant to the lesson
rule -- something that must be followed
insight -- used to re-emphasize a key point
tip --
advanced -- for advanced readers
practice -- a best practice. This one gets used a lot.
warning -- a warning to the user about some language pitfall or obstacle.
vs -- for visual studio users
cb -- for code::blocks uers
gcc -- for G++ users
windows -- for Windows users
linux -- for linux users
related -- intended for related content. Not sure if this is actually used.
author -- author’s note
reminder -- intended to remind the reader about something. Not sure if this is actually used.

[note qa title=”Question text”]
Answer text

[/note]

[quiz number=”1″]

Quiz direction

[hint]optional hint text[/hint]

[solution]
Solution to the quiz (can contain other tags, like [code])
[/solution]
[/quiz]

[link prevnext]

Used at bottom of rewritten lessons to insert a block containing the links to the previous and next articles. The current, previous, and next articles must be in the lesson map for this to work (here).

[image src=”Subfolder/image.png”]

Subtags supported:
test -- if on test server, don’t automatically redirect URL to normal server
media -- look in media library directories
alt=”text” -- alt text