Darmstadt University of Applied Sciences
Faculty of Computer Science
Submitted in partial fulfillment of the requirements for the degree of
Bachelor of Science (B.Sc.)
by
Zebreus
Matriculation number: XXXXXX
- First Examiner
-
Prof. Dr. Some Person
- Second Examiner
-
Prof. Dr. Another Person
Suppose you are writing a thesis; you probably need this bit to confirm that you wrote it all by yourself. This template adds the signature-required CSS class, which adds a nice line where you can write your name.
If you are not writing a thesis, just delete this whole section.
Darmstadt, 5.7.2023
Zebreus
This document presents the Asciidoctor.js thesis template, which offers a versatile and easily understandable alternative to traditional typesetting systems for scientific writing. The template leverages the flexibility of web technologies, allowing seamless design modifications and rendering of PDF and website versions of the thesis. The source document structure resembles markdown, enhancing its readability. This abstract provides an overview of the template’s benefits, getting started instructions, toolchain details, customization options using JavaScript, integration of source code listings and syntax highlighting, philosophical considerations behind the design decisions, and a comprehensive guide to using the template’s features for scientific writing. Overall, the Asciidoctor.js thesis template provides a user-friendly and efficient approach for creating scientific theses, offering enhanced readability and ease of customization compared to traditional typesetting systems.
Scientific writing plays a vital role in conveying research findings and academic knowledge. As traditional typesetting systems for scientific documents can be complex, there is a growing interest in alternative approaches that prioritize flexibility, readability, and ease of use. The Asciidoctor.js thesis template offers a comprehensive framework for creating well-structured and visually appealing theses. By leveraging web technologies, this template allows for seamless design modifications and facilitates the generation of PDF and website versions. In this introduction, we will explore the key features, benefits, and practical considerations of the Asciidoctor.js thesis template, highlighting its potential to revolutionize scientific writing.
Figures, tables, and listings are automatically numbered and added to their respective list after the table of contents.
All chart types except for vega-lite should just be used as asciidoctor-kroki charts. You can reference your chart in the text like Sample nomnoml chart, by giving it an id, in this case, sample-nomnoml-chart.
[<actor>Jolly;Sailor] [Jolly;Sailor]->[Pirate] [Jolly;Sailor]->[rum] [Pirate| [beard]--[parrot] [beard]-:>[foul mouth] ] [Pirate]-> *[rum|tastiness: int|swig()] [<abstract>Marauder]<:--[Pirate] [<table>mischief| bawl | sing || yell | drink ] [Pirate] - 0..7[mischief] #gutter: 10 #lineWidth: 1.25 #stroke: #000000 #font: Spectral #fill: #f7f8f7; #ffffff; #f7f8f7; #ffffff; #f7f8f7; #ffffff
All chart types except for vega-lite should just be used as asciidoctor-kroki charts. You can reference your chart in the text like <<sample-nomnoml-chart>>, by giving it an id, in this case, `sample-nomnoml-chart`.
.Sample nomnoml chart
[nomnoml,id=sample-nomnoml-chart]
....
[<actor>Jolly;Sailor]
[Jolly;Sailor]->[Pirate]
[Jolly;Sailor]->[rum]
[Pirate|
[beard]--[parrot]
[beard]-:>[foul mouth]
]
[Pirate]-> *[rum|tastiness: int|swig()]
[<abstract>Marauder]<:--[Pirate]
[<table>mischief| bawl | sing || yell | drink ]
[Pirate] - 0..7[mischief]
#gutter: 10
#lineWidth: 1.25
#stroke: #000000
#font: Spectral
#fill: #f7f8f7; #ffffff; #f7f8f7; #ffffff; #f7f8f7; #ffffff
....link:assets/keccak_clang_speed.wavejson.json[role=include]
.Sample wavedrom chart
[wavedrom,id=sample-wavedrom-chart]
....
include::assets/keccak_clang_speed.wavejson.json[]
....To make the chart extend over the margins of the page, add a slightly-oversized, oversized, or completely-oversized to the chart.
link:assets/minmax_speed_control_flow.dot[role=include]
.Sample graphviz graph
[graphviz.slightly-oversized,id=minmax-speed-cfg,width=570px]
....
include::assets/minmax_speed_control_flow.dot[]
....Vega-lite is the preferred way to display any data-driven charts. You use the included vega-chart.adoc script to include vega-lite charts. It detects if the document is currently built for a browser or as a PDF. If the document is built for a browser, it will include the chart directly via the Vega javascript library. That way, the chart supports tooltips and other interactive features.
.Sample vega-lite chart
:chart-id: id=minmax-area
:vega-lite-filename: processed-assets/minmax_overview_area.vl.json
include::scripts/vega-chart.adoc[]Asciidoc also supports source listings. A short verilog listing is shown in Listing 3.
module Blinker (input clock, output blinker);
reg [6:0] counter = 0;
reg state = 0;
always @(posedge clock) begin
counter <= counter + 1;
if (counter == 9) begin
state <= ~state;
counter <= 0;
end
end
assign blinker = state;
endmoduleListing 4 shows a long Rust listing. This template has a .linenums class that can be added to code listings to enable line numbers. The normal AsciiDoc linenums attribute is not supported.
link:assets/long_rust_listing.rs[role=include]Your code should be no wider than 80 characters. If it is, try using the oversized classes to avoid unnecessary line breaks.
Asciidoc supports tables. A simple table is shown in Table 1.
| Port | Size per channel in bits | Description |
|---|---|---|
|
\$1\$ |
Set to 1 to read from the channel. |
|
\$1\$ |
Set to 1 to write to the channel. |
|
\$log_2("dataWidth") + 1\$ |
Set the width of bits that should be written to the memory. It can be a value between 0 and the width of your data. |
|
\$"addressWidth"\$ |
Select the address this channel should operate on. |
|
\$"dataWidth"\$ |
Contains the data that will be written to memory if |
|
\$"dataWidth"\$ |
Contains the data that was read from memory if |
|
\$1\$ |
Nonzero if the memory is not ready. |
Asciidoc supports referencing other parts of the document. To reference other parts of the document, you can use the [id] syntax. The template styles them like this:
Table 1 and Listing 3 and Sample wavedrom chart and [_using_figures] and [invalid-reference]
When you first use abbreviations, you should introduce them like field-programmable gate array (FPGA). You should also add them to the [_list_of_abbreviations]. Every abbreviation added to that list will automatically be linked when it is used in the document.
For example, we can just use FPGA, HLS, RAII, and LLVM IR in any sentence, and they will be linked without any special markup.
I also recommend adding a link to a more detailed web source like Wikipedia to every entry in the list of abbreviations. I usually have the list of abbreviations as the first section after the main content.
To see an example of a list of abbreviations, look at the source for [_list_of_abbreviations].
This template uses the built-in bibliography support of Asciidoctor. It is relatively basic, but I found it to work really well in practice. The Readme goes into more detail on how you can structure your bibliography; alternatively, you can directly look into the source of this document.
To cite a source, just reference it like a figure, table, or section. References to sources should grammatically not be a part of your sentence.
The Rust programming language [Kla23] is a modern systems programming language. It is the most loved programming language of the last years [Sta16] [Sta20] [Sta23]. On an unrelated note, Microsoft uses FPGAs to accelerate their Bing search engine [Nan16], and Bambu [Fer21] is a framework for HLS. I don’t think Microsoft uses Bambu for their FPGAs; they probably use SystemVerilog, the most common language for hardware design [Soz22].
Just add an extra chapter named Appendix after the references and dump your figures and whatnot there. You can reference them like any other figure. Listing 5 was banished into the appendix because I needed to put something there as an example.
In conclusion, the Asciidoctor.js thesis template offers a flexible, readable, and user-friendly approach to scientific writing. By leveraging web technologies, the template enables easy customization and modification of the document’s design. The inclusion of interactive figures using asciidoctor-kroki and vega-lite enhances the visual presentation of data and improves the overall reading experience. The template’s support for source listings and syntax highlighting ensures clear and legible code representation. It is important to note that this section was generated with an AI language model trained by OpenAI because a conclusion does not make sense in a dummy document like this. With its comprehensive documentation and practical examples, the Asciidoctor.js thesis template empowers users to create well-structured and visually appealing scientific theses. By combining the simplicity of markdown-like syntax with the power of web technologies, this template sets a new standard for scientific writing, making the process more accessible and enjoyable for researchers and students alike.
This template is by no means perfect; there are still some things that could be improved. For example, the template does not support footnotes because I don’t need them. Images are also untested but should work exactly like figures. Admonitions look acceptable but could definitely be fancier. But who uses admonitions in scientific writing anyway? There are probably more AsciiDoc features I don’t use that may not work properly. As the default stylesheets are included in the template, most should still look fine. I also do not like blue links. Maybe I should style them differently.
The template could also be adjusted to work well with Asciidoctor slides, but I have not tried that yet. Thanks for reading to the end, have a nice day and a cookie 🍪.
-
[Nan16] Razvan Nane, Vlad-Mihai Sima, Christian Pilato, Jongsok Choi, Blair Fort, Andrew Canis, Yu Ting Chen, Hsuan Hsiao, Stephen Brown, Fabrizio Ferrandi, Jason Anderson, Koen Bertels
A Survey and Evaluation of FPGA High-Level Synthesis Tools
IEEE Transactions on Computer-Aided Design of Integrated Circuits and Systems
10.1109/tcad.2015.2513673 📁
-
[Fer21] Fabrizio Ferrandi, Vito Giovanni Castellana, Serena Curzel, Pietro Fezzardi, Michele Fiorito, Marco Lattuada, Marco Minutoli, Christian Pilato, Antonino Tumeo
Invited: Bambu: an Open-Source Research Framework for the High-Level Synthesis of Complex Applications
ACM/IEEE Design Automation Conference
10.1109/DAC18074.2021.9586110 📁
-
[Soz22] Emanuele Del Sozzo, Davide Conficconi, Alberto Zeni, Mirko Salaris, Donatella Sciuto, Marco D. Santambrogio
Pushing the level of abstraction of digital system design: A survey on how to program FPGAs
ACM Computing Surveys
10.1145/3532989 📁
-
[Sta16] Stack Overflow
Stack Overflow Developer Survey 2016
[Online; accessed 5.7.23]
insights.stackoverflow.com/survey/2016
-
[Sta20] Stack Overflow
Stack Overflow Developer Survey 2020
[Online; accessed 5.7.23]
insights.stackoverflow.com/survey/2020
-
[Sta23] Stack Overflow
Stack Overflow Developer Survey 2023
[Online; accessed 5.7.23]
survey.stackoverflow.co/2023 -
[Kla23] Steve Klabnik, Carol Nichols
The Rust programming language
[Online; accessed 5.7.23]
doc.rust-lang.org/stable/book
link:assets/long_rust_listing.rs[role=include]