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

Showcase: a test article

Notes published the
Notes updated the
10 - 13 minutes to read, 2621 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 the features I am currently using.

I 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

.Unordered list:
  * Apple
  * Banana
  * Orange

.Ordered list:
    . Step 1
    . Step 2
    .. Step 2a
    .. Step 2b
    . 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

Code

Inline code

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

For example: int main(), written as

`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 (kbd:[F11]), Ctrl+Space bar (kbd:[Ctrl + Space bar]), AltGr (kbd:[AltGr])

Windows-specific keys: ⊞ Win, ≡ Menu

Apple-specific keys: ⌥ Option and ⌘ Cmd

There are no Linux-specific keys. The Sun Keyboard has a meta key: ◆. The Space-cadet keyboard also has hyper (✦), Control (⎈), and Super (❖).

The space bar might be denoted with ␣

There are a lot of arrows:

  • simple arrows ⬅, ⬇, ⬆, and ➡

  • page arrows PgUp🠕, PgDn🠗, ⇱ (sometimes Home), and ⇲ (sometimes End)

  • tab arrow Tab ↹ (Tab ⇥ and backtab ⇤ on Apple)

  • backtab Tab ⇤

  • enter/return ⌅ Enter (alternate: ⌤ Enter, ↵ Enter, and ⎆ Enter), and ↵ Return (or ⏎ Return, ↩)

  • backspace ← Backspace, less often ⌫

  • shift and caps ⇧ Shift, ⇩ Shift Lock, and ⇪ Caps Lock

  • scroll Lock Scroll Lock (⇩ Rollen in Germany)

  • Alt key ⎇, even if I’ve never seen this symbol in the wild, just Alt

  • Delete key ⌫ and Forward delete key ⌦ key, although most keyboards have Del without the arrow

  • Escape key ⎋, even if I’ve never seen this symbol in the wild, just Esc

  • the eject symbol on some laptops ⏏, especially if you have a DVD drive

Listbox

Works only with an unordered list (ie with *)

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

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

  • normal list item (* normal list item)

Emoji/Emoticon/Other special characters

It is possible to write the emoji directly: 🎉.

Some environments, like Windows 🗄️ and KDE 🗄️ have an integrated emoji picker.

If your environment lacks on, it is always possible to copy them from a website, like emojipedia, emojipicker, graphemica and other sites.

Otherwise, use an escape sequence like 🎉 (in this case, it is &#127881; I am not sure if it works when converting AsciiDoc to something that is not HTML)

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 is normally easier to read and 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 simple quote

[quote, attribution, citation title, optional additional data]
____
Text to quote
____

Text to quote

— attribution
citation title

A longer quote

[quote, Monty Python and the Holy Grail]
____
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?
____

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 the quote contains a link, a piece of code, or ,, then 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

A word consists of a sequence of letters, digits, and underscores, or a sequence of other non-blank characters, separated with white space (spaces, tabs, <EOL>). […​] An empty line is also considered to be a word.

— vi --cmd ":h word"

Links

  • just write the link down: https://www.example.com

  • A global link (written as https://www.example.com[global link])

  • Nonglobal links cannot be "naked"

  • Local link home (written as link:/[home])

  • Relative link up (written as link:../../[up])

  • Internal links

  • link separated by /: AdoptOpenJDK/Adoptium (written as https://adoptopenjdk.net/[AdoptOpenJDK]/link:https://adoptium.net/[Adoptium])

  • as best practice, I’m going to archive linked content, and provide two links per url in a form similar to the following one EncodePointer function 🗄️ https://docs.microsoft.com/previous-versions/bb432254(v=vs.85)[EncodePointer function]{nbsp}^link:/archive/pages/docs.microsoft.com//previous-versions/bb432254(v=vs.85)/[🗄️,opts=nofollow]^

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

Written as

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

Inserted with

[#img-cpp]
.The https://github.com/jwkratz/cpp_logo[{cpp} logo], by Jeremy Kratz, licensed under https://creativecommons.org/publicdomain/zero/1.0/[CC0 1.0 Universal]
[link={imagesdir}multimedia/cpp_logo.svg]
image::/multimedia/cpp_logo.svg["{cpp} logo",align="center"]

Video

Showcasing the Black Castle game on an Android phone with one bumper as a button

Audio

Example audio

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

 
[cols=2*,options=header]
|===
|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.

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 
++++
<math title="2^k = j + 2^(k-1)-1" xmlns="http://www.w3.org/1998/Math/MathML" display="block">
        <msup>
          <mn>2</mn>
          <mi>k</mi>
        </msup>
        <mo>=</mo>
        <mi>j</mi>
        <mo>+</mo>
        <msup>
          <mn>2</mn>
          <mrow>
            <mi>k</mi>
            <mo>-</mo>
            <mn>1</mn>
          </mrow>
        </msup>
        <mo>-</mo>
        <mn>1</mn>
    </math>
++++

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

pass:[
<math title="n^h" xmlns="http://www.w3.org/1998/Math/MathML">
    <msup>
    <mi>n</mi>
    <mi>h</mi>
    </msup>
</math>]

To create the same formula offline, you can use asciimath to generate the mathml snippet: asciimath 'n^h'.

The attributes title and xmlns are unfortunately not part of the output of asciimath, but it can be fixed with a wrapper script:

# "$1" is the formula
escaped=$(printf "%s" "$1" | sed -e 's|\&|\&amp;|g' -e 's|"|\&quot;|g' -e 's|<|\&lt;|g' );
header=$(printf '<math title="%s" xmlns="http://www.w3.org/1998/Math/MathML">' "$escaped");
asciimath "$1" | perl -pe "s(\Q<math>)($header)"
Note 📝
 the value in xmlns is an http address, and not https. This is by design, as described on the MathML website.

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.