Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Asciidoc export option #137

Merged
merged 1 commit into from
Jan 30, 2019
Merged

Add Asciidoc export option #137

merged 1 commit into from
Jan 30, 2019

Conversation

CosmicToast
Copy link
Contributor

This adds an option to export to an asciidoc-style table.
Functionally similar to the current markdown exporter.

Signed-off-by: Chloe Kudryavtsev <toast@toastin.space>
@sharkdp
Copy link
Owner

sharkdp commented Jan 30, 2019

Thank you very much for your contribution!

Can you please show an exemplary output here in the description and give a short explanation why we would need an AsciiDoc export option in addition to the Markdown export option (I am not familar with AsciiDoc)?

@CosmicToast
Copy link
Contributor Author

Absolutely!

hyperfine --export-asciidoc /dev/tty 'sleep 0.1' 'sleep 0.2' will currently output the following:

[cols="<,>,>"]
|===
| Command | Mean [ms] | Min…Max [ms]

| `sleep 0.1`
| 107.2 ± 2.2
| 100.4…109.2

| `sleep 0.2`
| 206.7 ± 2.6
| 200.9…209.1
|===

Here is an image of what that looks like under default CSS settings, as per asciidoctorjs.

As to what asciidoc is, and why it should be used...

AsciiDoc is another markup language (similar to Markdown).
It has a lot more functionality behind it (it should be roughly feature-compatible with docbook - its origin).
The current canonical implementation is AsciiDoctor, you can take a look at the plethora of features in the user manual.
The primary issue with markdown is that it alone is generally not sufficient - and thus there are many extended variants (github markdown, gitlab markdown, commonmark, etc), whereas asciidoc is relatively complete (and currently being standardized), making it a nicer common platform, with sufficient features for most other uses (I use it for technical documentation, writing manual pages, research papers, bookwriting, and so on).
Or, shorter - Markdown is a quick but useful tool for getting some text into html.
Asciidoc is a comprehensive content markup, with many available targets, and useful for all sorts of use-cases.

As for the technical side, asciidoc tables look/work differently from markdown ones (user manual section on tables).

I'm currently running some expansive benchmarks on common unix compressors, and the content will be too complex for markdown (and I tend to write in asciidoc to begin with).
While it's too late for me to restart the (very long) process now, this patch will mean I won't need to construct the tables by hand next time.

@sharkdp
Copy link
Owner

sharkdp commented Jan 30, 2019

Thank you for the detailed explanation!

I guess there is no harm in extending the number of export formats (except for the larger amount of code) :-)

@sharkdp sharkdp merged commit e31dc91 into sharkdp:master Jan 30, 2019
@CosmicToast CosmicToast deleted the asciidoc branch January 30, 2019 20:27
@sharkdp
Copy link
Owner

sharkdp commented Jun 8, 2019

Released in v1.6.0.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants