ahrf - [a]scii (or [a]wk) [h]uman [r]eadable [f]ile
ahrf is an
awk script designed to interpret a simple and straightforward
ASCII file format. I wrote it to share my personal documentation, which is
written in plain text files. They can be exported to HTML.
The main goal was... readability.
- One requirement:
- Supporting many
awk) (cf "Compatibility")
- Simple syntax
- Easy to use / remember / extend
- Designed to work with wswsh
- File format can be parsed by almost everything:
: My important page title :
<h1>My important page title</h1>
:: This is the category title ::
<h2>This is the category title</h2>
and so on...
::: ::: for <h3></h3> :::: :::: for <h4></h4> ::::: ::::: for <h5></h5> :::::: :::::: for <h6></h6>
It's possible to define a heading, without the second
::: field (but it
would be less readable):
::: My title without the second field
You just need to put your paragraph inside the file. Nothing else is required:
DTLS memory leak from zero-length fragments (CVE-2014-3507) OpenSSL DTLS anonymous EC(DH) denial of service (CVE-2014-3510) Race condition in ssl_parse_serverhello_tlsext (CVE-2014-3509) OpenSSL TLS protocol downgrade attack (CVE-2014-3511)
<p>DTLS memory leak from zero-length fragments (CVE-2014-3507) OpenSSL DTLS anonymous EC(DH) denial of service (CVE-2014-3510) Race condition in ssl_parse_serverhello_tlsext (CVE-2014-3509) OpenSSL TLS protocol downgrade attack (CVE-2014-3511)</p>
Line breaks are supported. You just need to add one or more "ghost" space(s) at the end of the line:
This could be exploited in a Denial Of Service attack.▉ This issue affects OpenSSL 1.0.1 server implementations for both SSL/TLS and DTLS regardless of whether SRTP is used or configured.▉ Reported by LibreSSL project.
<p>This could be exploited in a Denial Of Service attack.<br> This issue affects OpenSSL 1.0.1 server implementations for both SSL/TLS and DTLS regardless of whether SRTP is used or configured.<br> Reported by LibreSSL project.</p>
Paragraphs can start by:
A-Z: All letters uppercase
a-z: All letters lowercase
Code blocks must start by 4
= at least.
==== Filesystem Size Used Avail Use% Mounted on /dev/sda5 12G 2.5G 8.6G 23% / dev 3.9G 0 3.9G 0% /dev run 4.0G 592K 3.9G 1% /run tmpfs 4.0G 0 4.0G 0% /dev/shm ====
<pre><code>Filesystem Size Used Avail Use% Mounted on /dev/sda5 12G 2.5G 8.6G 23% / dev 3.9G 0 3.9G 0% /dev run 4.0G 592K 3.9G 1% /run tmpfs 4.0G 0 4.0G 0% /dev/shm</code></pre>
======= ls /usr/local/etc/rc.d/ =======
You need to add one or more space(s) after
*. If you omit that, the
item(s) will be ignored.
* Eat cooked meat * Buy french bread * Peel potatoes * Drink beers
<ul> <li>Eat cooked meat</li> <li>Buy french bread</li> <li>Peel potatoes</li> <li>Drink beers</li> </ul>
* Homemade sausage * Apple pie *Be fast * Don't be in a hurry
<ul> <li>Homemade sausage</li> <li>Apple pie</li> <li>Don't be in a hurry</li> </ul>
The "list" has to be started by
. If not, it won't be matched.
 https://github.com/  http://netbsd.org/  http://ywstd.fr/  http://www.libressl.org/
<ul> <li> <a href="https://github.com/">https://github.com/</a></li> <li> <a href="http://netbsd.org/">http://netbsd.org/</a></li> <li> <a href="http://ywstd.fr/">http://ywstd.fr/</a></li> <li> <a href="http://www.libressl.org/">http://www.libressl.org/</a></li> </ul>
There is no specific regex for the comments. If the line doesn't "satisfy"
the above specs, it'll be just ignored. However, starting comments by
is perfect. The readers will be able to see them, in less than 0,25 ms
(yes, many configuration files use
Common shell symbols
To avoid invalid HTML code, the symbols
& are automatically
replaced by their HTML counterparts.
The valid ouput can be found within the files
*.outvalid inside the
It's a VERY good idea to check those results to understand how
To prevent introducing regressions when regexes are reworked, improved or
sh script was written to check and compare
ahrf output. It's
verify_regr.sh. It can be launched via
your_shell verify_regr or
make check for the lazy men.
make clean deletes the invalid files from
the last checking. I strongly advise you to run it for every changes!
awk variants were validated using the regressions test (no
The versions are printed here:
Dec 20, 2012
mawk(some problems before
mawk 1.3.4 20141027&
awk version 20110810
awk version 20121220(thanks to @justincormack)
GNU Awk 4.1.1
nawk), but I don't have the exact version number. However, I do not plan to test this "variant" for every new changes.
nawk when I wrote this script. It can be found
make all (or simply
make) will launch the tests for every variants
This script wasn't created to mimic or replace
markdown syntax. Therefore,
I do not ask or force anybody to adopt it. I want to write my own documentation
or cheatsheets using an easy "system".
markdown can be very frustrating when you use a lot of preformatted text
or lists and the result is sometimes totally broken and wrong. For example,
when I wrote that
README.md, I encountered many times malformed output or
I'm not even talking about the dozens of differents variants / implementations... And do not tell me I don't know what I'm talking about because I "played" thousands of times with
Maybe. I'm not enough confident to write a bugless script. Report them! If you notice something wrong, try to provide me an ascii file with your lines. I'll be able to work on/debug it.
Code created by Ypnose, under BSD (3-Clause) License
Thanks to Alexander for serving me as a guinea pig.