The C++ logo, by Jeremy Kratz, licensed under CC0 1.0 Universal

Showcase: a test article

Notes published the
Notes updated the
8 - 10 minutes to read, 2060 words
Categories: editing web
Keywords: asciidoctor editing web

What is this document

I use PHP for compiling the webpage, and from time to time I change the CSS or some rules on how the articles are generated.

Most of the time the changes are little improvements, but sometimes there are regressions, like an image not scaled correctly or tables behaving strangely.

As I am not going to re-read everything I’ve written with the different browsers I use, I decided it would be a good idea to have a document that uses more or less all features I am currently using.

I actually have been using something like that for a long time, but it was incomplete and partially broken.

Subsection

Just a wall of text in a subsection.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Risus feugiat in ante metus dictum at tempor commodo ullamcorper. Ut consequat semper viverra nam libero. Posuere ac ut consequat semper. Eget gravida cum sociis natoque penatibus et magnis dis. Sapien eget mi proin sed libero enim sed faucibus. Urna et pharetra pharetra massa massa ultricies mi. Vivamus at augue eget arcu dictum varius. Ultrices neque ornare aenean euismod elementum nisi quis eleifend. Nisl condimentum id venenatis a condimentum. Sollicitudin tempor id eu nisl nunc mi. Porta nibh venenatis cras sed felis. Hendrerit dolor magna eget est lorem ipsum dolor sit. Tortor at auctor urna nunc id cursus metus aliquam eleifend. Eu augue ut lectus arcu bibendum at varius vel. Placerat duis ultricies lacus sed turpis tincidunt id aliquet. Lacus vestibulum sed arcu non odio euismod lacinia at. Amet consectetur adipiscing elit pellentesque habitant morbi tristique senectus et. In ornare quam viverra orci sagittis.

Formattings

It is possible to format whole words or only a part of them, but there can be some limitations when nesting formattings.

Some bold text.

This is is italic. Bold italic.

This is monospace. This is bold and monospace. This is monospace; bold and italic.

Some highlighted text. This is highlighted, bold, italic and monospace.

Some underlined text, and some curly underlined text. This is underlined, bold, italic and monospace.

Some striked text.

Currently underlined and struck text do not appear as such in lynx (and possibly other textual browsers) as they are rendered through CSS.

Use \ for escaping. For example *bold* (\*bold*) will not appear as bold (*bold*) text.

Paragraphs

Paragraphs are separated in source code by empty lines. Two adjacent lines are part of the same paragraph.

One best practice is to write one sentence per line. This makes diffing between revisions easier.

Lists

Unordered list:

  • Apple

  • Banana

  • Orange

Ordered list:

  1. Step 1

  2. Step 2

    1. Step 2a

    2. Step 2b

  3. Step 3

Ordered list starting from five:

  1. Step five

  2. Step six

Alphabetical list:

  1. one

  2. two

    1. two-one

    2. two-two

  3. three

Description list:
CPU

The brain of the computer.

Hard drive

Permanent storage for the operating system and/or user files.

RAM

Temporarily stores information the CPU uses during operation.

Keyboard

Used to enter text or control items on the screen.

Horizontal description list:
CPU

The brain of the computer.
Hard drive

Permanent storage for the operating system and/or user files.
RAM

Temporarily stores information the CPU uses during operation.
Nested lists:
Operating Systems
Linux

  1. Fedora

    • Desktop

  2. Ubuntu

    • Desktop

    • Server

BSD

  1. FreeBSD

  2. NetBSD

Windows

  1. XP

    • SP1

    • SP2

    • SP3

  2. 10

Multiline-lists:

  • The header in AsciiDoc is optional, but if If it is used it must start with a document title.

  • Optional Author and Revision information immediately follows the header title.

  • The document header must be separated from the remainder of the document by one or more blank lines and cannot contain blank lines.

Code

Inline code

Inline code can be added with a backtick (`), it’s the equivalent of monospaced text.

For example: int main().

Code blocks

Code block always creates a new paragraph

Some C++ code
#include <cstdio> // (1)

int main(){
    std::puts("Hello World"); // (2)
}

  1. include basic io facilities

  2. Prefer puts to printf and streams when possible

even if there are no comments or title

echo "Hello World";

For a piece of code with many underscore characters: extern void *memset (void *__s, int __c, size_t __n) __THROW __nonnull;. look at escape unconstrained formatting marks.

And an example of a larger C++ snippet, would be cool to autoformat on smaller screen size (maybe add line numbers)

Note that line numbers do not seem to generate valid HTML: [source%linenums, cpp] and [source, cpp, linenums]. On the other hand highlight works…​

Some C++ code, with a couple of highlighted lines ([source, cpp, highlight=7..9;12..15])
#include <algorithm>
#include <string_view>

template <class... S>
std::string concat(const S&... strs) {
  std::string_view views[]{strs...};
  int totalsize = std::accumulate(std::begin(views), std::end(views), 0,
    [](int count, std::string_view v){return count + v.size();
  });
  std::string result(totalsize, '\0');
  int cur_pos = 0;
  for(const auto& v : views){
    std::copy(v.begin(), v.end(), result.begin() + cur_pos);
    cur_pos += v.size();
  }
  assert(cur_pos == totalsize);
  return result;
}

std::string a, b, c;
// fill a, b,c
auto result = concat(a, b, c);
Some code with additional formatting; name should be bold
System.out.println("Hello <name>")

Unfortunately does not work well when formatting multiple words that are normally highlighted differently.

Thus System.out.println("Hello *<name>*") is not a problem, but System.out.println("Hello *<name>")* is.

Thus it might make sense to disable formatting:

int foo(int);
int bar(void);

Pay attention to unwanted callouts!

Buttons, keyboard, and menu

Buttons

Use X (btn:[X]) to denote button X.

Android programs often use ⁝ or ☰ for denoting a menu.

Examples:

  • Press the OK button when you are finished

  • Select a file in the file navigator and click Open

Menu

Often menus are represented by arrows.

Examples

  • To save the file, select File › Save. (written as menu:File[Save])

  • Select View › Zoom › Reset to reset the zoom level to the default setting. (written as menu:View[Zoom > Reset])

Keyboard

Using a different graphic helps to make clear which keys one has to type.

For example: F11, Ctrl+Space bar, AltGr

Windows-specific keys: ⊞ Win, ≣ Menu

Apple-specific keys: ⌥ Option and ⌘ Cmd

There are no Linux-specific keys, but the Sun Keyboard has a meta key: ◆.

There are a lot of arrows:

  1. simple arrows ⬅, ⬇, ⬆, ➡

  2. page arrows PgUp🠕, PgDn🠗, ⇱ (Home), ⇲ (End)

  3. tab arrow Tab ↹ (Tab ⇥ on Apple)

  4. enter/return ⌅ Enter, ↵ Return

  5. backspace ← Backspace

  6. shift and caps ⇧ Shift, ⇩ Shift Lock, ⇪ Caps Lock

  7. scroll Lock Scroll Lock (⇩ Rollen in Germany)

  8. Alt key ⎇, even if personally never seen this symbol in the wild, just Alt

Listbox

Works only with an unordered list (ie with *)

  • ✓ checked ( * [x], can replace * with x, should show something like ✓, ☑ or ☒)

  • ❏ not checked ( * [ ] should be an empty box, like ❏ or ☐)

  • normal list item

Emoji/Emoticon/Other special characters

It is possible to write the emoji directly: 🎉. It can be copied from emojipedia, emojipicker, graphemica and other sites or programs like Emoji picker on KDE and since Windows 10.

Otherwise use an escape sequence like 🎉 (in this case: &#127881;, unsure if it works when creating another type of document)

Some text is substituted automatically:

  • Copyright: © (written as (C) should appear as ©)

  • Registered: ® (written as (R) should appear as ®)

  • Trademark: ™ (written as (TM) should appear as ™)

  • Em dash: — (written as -- should appear as —)

  • Ellipsis: …​ (written as ... should appear as …)

  • Single arrows: →, ← (written as ->, <- should appear as →, ←)

  • Double arrows: ⇒, ⇐ (written as =>, <= should appear as ⇒, ⇐. note: different from the one used for keys: ➡, ⬅ )

  • Typographic apostrophe: Sam’s (written as Sam's should appear as Sam’s)

Text-based emoticons are not converted automatically ;-)

There are also emoticons: ☹,☺,☻

ASCII is easier to handle and more portable, but symbols can make the content more clear (like the keyboard symbols). Also using, for example, emoji symbols instead of escape sequences are normally easier to read/edit.

¯\_(ツ)_/¯ (written as ¯\\_(ツ)_/¯)

Subscript and superscript

DAVx⁵ and DAVx5 are unfortunately not the same, the second is easier to type (DAVx^5^), but the first is the name of the program.

Similar to superscripts, it is possible to write subscripts (H~2~O): H2O

Footnotes

This ends with a footnote.⁠[1]

Use {wj} as described in this article to improve footnotes, at least until this issue is addressed.

References

The Pragmatic Programmer [pp] should be required reading for all developers. To learn all about design patterns, refer to the book by the “Gang of Four” [gang].

Quotes

A small quote

Text to quote

— attribution
citation title and information

A longer quote

Dennis: Come and see the violence inherent in the system. Help! Help! I’m being repressed!

King Arthur: Bloody peasant!

Dennis: Oh, what a giveaway! Did you hear that? Did you hear that, eh? That’s what I’m on about! Did you see him repressing me? You saw him, Didn’t you?

— Monty Python and the Holy Grail

A quote with a linked reference. If a link or , is part of the information you need to use ' (if ' is part of the citation/information, then no idea what to do)

If you don’t know where you are going, any road will get you there.

— Charles Lutwidge Dodgson
Mathematician and author, also known as Lewis Carroll

Links

When referring to the same website, avoid global links, as it makes testing locally easier.

Internal links are created automatically for chapters, and can be created manually with [#_internal-link]

Admonitions

Warning ⚠️
 A warning
Caution
 act carefully!
Important !!
 Use to mark something important
Tip 💡
 just a tip
Note 📝
 note to self

A note with a long text to see how it wraps:

Note 📝
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Risus feugiat in ante metus dictum at tempor commodo ullamcorper. Ut consequat semper viverra nam libero. Posuere ac ut consequat semper. Eget gravida cum sociis natoque penatibus et magnis dis. Sapien eget mi proin sed libero enim sed faucibus. Urna et pharetra pharetra massa massa ultricies mi. Vivamus at augue eget arcu dictum varius. Ultrices neque ornare aenean euismod elementum nisi quis eleifend.

Images

A centered image

C++ logo
Figure 1. The C++ logo, by Jeremy Kratz, licensed under CC0 1.0 Universal

Tables

A minimal table (tables should always have a header for accessibility):

Name Group

Firefox

Web Browser

Ruby

Programming Language

Mouse

An animal, or peripheral

Every second row should have a different background color.

A bigger table, copied from this notes, should be larger than the maximum width of any paragraph.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Risus feugiat in ante metus dictum at tempor commodo ullamcorper. Ut consequat semper viverra nam libero. Posuere ac ut consequat semper.

If there is physically not enough space, only the table should have a horizontal scrollbar.

ctor/dtor inst compiler visibility weak const static link other settings

4

4

gcc/clang

default/hidden

na

c/nc

s/ns

int

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

4

4

msvc

na

na

c/nc

s/ns

int

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

4

4

mingw

default/hidden

na

c/nc

s/ns

int

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Math

A block MathML formula

2 k = j + 2 k - 1 - 1

and an inline n h formula, both created with asciimatheditor, it can be saved locally.

Those formulas might not work in chrome-based browsers.

References

  • [pp] Andy Hunt & Dave Thomas. The Pragmatic Programmer: From Journeyman to Master. Addison-Wesley. 1999.

  • [gang] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.

1. And the footnote is placed here

Do you want to share your opinion? Or is there an error, some parts that are not clear enough?

You can contact me anytime.