Showcase: a test article
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.
T
his is monospace
. T
his is bold and monospace
. T
his is monospace; bold and italic
.
Some highlighted text. T
his is highlighted, bold, italic and monospace
.
Some underlined text, and some curly underlined text. T
his 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
-
Apple
-
Banana
-
Orange
-
Step 1
-
Step 2
-
Step 2a
-
Step 2b
-
-
Step 3
-
Step five
-
Step six
-
one
-
two
-
two-one
-
two-two
-
-
three
- 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.
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. |
- Operating Systems
-
- Linux
-
-
Fedora
-
Desktop
-
-
Ubuntu
-
Desktop
-
Server
-
-
- BSD
-
-
FreeBSD
-
NetBSD
-
- Windows
-
-
XP
-
SP1
-
SP2
-
SP3
-
-
10
-
-
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
#include <cstdio> // (1)
int main(){
std::puts("Hello World"); // (2)
}
-
include basic io facilities
-
Prefer
puts
toprintf
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…
[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);
name
should be boldSystem.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.
-
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.
-
To save the file, select
. (written asmenu:File[Save]
) -
Select
to reset the zoom level to the default setting. (written asmenu: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:
-
simple arrows ⬅, ⬇, ⬆, ➡
-
page arrows PgUp🠕, PgDn🠗, ⇱ (Home), ⇲ (End)
-
tab arrow Tab ↹ (Tab ⇥ on Apple)
-
enter/return ⌅ Enter, ↵ Return
-
backspace ← Backspace
-
shift and caps ⇧ Shift, ⇩ Shift Lock, ⇪ Caps Lock
-
scroll Lock Scroll Lock (⇩ Rollen in Germany)
-
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*
withx
, 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: 🎉, 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.
Quotes
A small quote
Text to quote
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?
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.
Mathematician and author, also known as Lewis Carroll
Links
-
A global link: https://www.example.com (just write the link down)
-
A global link (written as
https://www.example.comglobal link
) -
Nonglobal links cannot be "naked"
-
Local link home (written as
link:/[home]
) -
Relative link up (written as
link:../..[up]
)
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
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
and an inline formula, both created with asciimatheditor, it can be saved locally.
Those formulas might not work in chrome-based browsers.
Do you want to share your opinion? Or is there an error, some parts that are not clear enough?
You can contact me anytime.