This will be replaced by the title of the document
Matías Senger Juan Carlos Captain Jack SparrowYo ho, yo ho, a pirate's life for me. Smart Guy

PDF is the most used format for scientific documents, be them reports, papers, slides, etc. The major advantage of this format is its universality, once a PDF file is produced it is assured that it will be properly rendered in any modern operating system using the appropriate software. However, it has a major drawback: It was designed to represent "paper-printed documents" and so it can only contain static text and images. This limits the way scientists present their results. Furthermore, the rate at which we read documentation is so high that most of the PDFs we read are never printed, we just read them from the screen. In view of this it is reasonable to have a new, modern format for such a purpose. Here I explore how the technologies behind websites can be addapted to this and present an example (this document itself).

This is a second paragraph in the abstract. Usually there is only one, but we can handle more if needed.

Table of contents

Introduction to HTML Scientific Document

"HTML Scientific Document" is an evolution to scientific documents in PDF format.

Why to replace the PDF format?

PDF is nowadays the most extended format for sharing scientific documents. A PDF document basically represents a bunch of paper sheets. This limits what your document can containBasically you can only put static text and images, that's all.. From my point of view:

What can replace the PDF format?

HTML, the technology behind websites, is as universal as PDFs but much more flexibleWith HTML you can create anything you can imagine, for example YouTube.. For me it looks as the perfect candidate for this jump as the hard part (implementing the machinery) is already solved.

Latex vs HTML

In physics, math and other related fields of science it is very common to write documents using Latex. Latex is very nice and powerful, it produces amazing PDF files. But this is preciselly the problem I see: It produces PDFs. If you write in Latex it is because in the end you want a PDF.

HTML, as Latex, is a markup language but, in contrast, it is much more widespread due to its masive usage in websites. The comunity of HTML users is infinitely bigger than the comunity of Latex users. Nowadays there is nothing Latex can do that HTML cannot do (for example beautiful equations). Even more, you don't need to install anything in order to create/view an HTML document because you already have a text editor and a web browser in all your devices.

In view of this it looks very reasonable for me to choose HTML as the basis for "the next generation of scientific documents" rather than Latex or anything else.

Still want a PDF?

You still want a PDF? Open this document with your favourite web broser, hit ctrl+print and save it as a PDF fileFirefox can do this, probably all other "famous" browsers can too. You may have to set up the zoom, margins, background, etc. such that it looks fine as in the browser. But believe me, it is trivial to get a good looking PDF from this.. There are probably other ways of getting a PDF from an HTML file.

Documentation and reference

Template

You can use the document you are reading right now as a template. It has everything you need in it. To get the source code visit this link or just open this file with a text editorIf you are in a web browser: "File → Save page as" and then open it with your favourite text editor..

Github repo

You can also download the source code of this file and the CSS and JavaScript that produces this output from this Github repo.

Examples

There are currently a few examples:

Still-to-do list

Though this is already looking good, there is still much work to do:

HTML Scientific Document

Here I will describe my current approach which produces a document as the one you are reading right now. Still not perfect but, from my point of view, already better than a PDF.

The structure of the documents

This is based in HTML so anything that applies to HTML also applies to this. The structure of an HTML-SD must follow the structure of an HTML document. As an example you can take the source code for this document, just select "view source" with your favourite web browser or download this file (using ctrl+s for example) and open it with a text editor.

Fully offline and stand alone document

Though HTML is usually encountered in online applications, off course you can do everything offline. In fact for the current application to scientific documents we would prefer to have a fully offline and standalone document in many cases. HTML Scientific Document was designed with this in mind so to obtain a fully offline and standalone document you just need to append the CSS and JavaScript files together with your HTML.

Currently the support for math equations requires internet connection.

Sections and sub-sections

Scientific documents are structured in sections, sub-sections, sub-sub-sections and so on. To accomplish this in HTML you can use the h1, h2,... tags. The scripting engine of HTML-SD that is linked to this HTML file will automatically number the sections and also produce a table of contents as we are used to in Latex. See for an example.

Example of how to create sections and sub-sections. <h1>This is a section</h1> <p>This is a paragraph.</p> <h2>This is a sub-section</h2> <p>This is a paragraph within the sub-section.</p>

Unnumbered sections

To insert unnumbered sectionsUnnumbered sections are not listed in the table of contents and cannot be referenced using <crossref>. just set the class attribute to "unnumbered". An example is shown in . Unnumbered sections example. <h3 class="unnumbered">This is an unnumbered section</h3> As a result of this you will get the following section:

This is an unnumbered section

This section will not be listed in the table of contents, it is just aesthetic. You can do this with any type of heading tag.

Sections with the same name

You can have sectioins with the same name, but if you do that you must make them different by assigning different ids to each of them. shows an example. Example of inserting multiple sections with the same name <h1>Numbered sections with the same name</h1> <!-- This section does not need an id because it is the first one with this name --> <h1 id="second section with the same name">Numbered sections with the same name</h1> <h1 id="third section with the same name">Numbered sections with the same name</h1> By doing this we obtain, for example, and .

Two sections with the same name

This section has the same name as , but they are different by the id attributeThe id attribute is not rendered in an HTML document so you will not see it in your web browser..

Two sections with the same name

This section has the same name as .Two sections with the same name require at least one of them with a different id. Otherwise they are the same section and we don't know which of them to refer to when there is a cross reference.

Mathematic equations

You can just write your equations using Latex code. For example $x^2+x+1=0$ becomes $x^2+x+1=0$ and $$e^{i\pi}+1=0$$ becomes $$e^{i\pi}+1=0$$

Numbered equations

To insert a numbered equation use the equation tag as shown in . Numbered equation example. <equation id="my first equation">$$\intop_0^\frac{\pi}{2} f(x)~dx=1$$</equation> As a result we get: $$\intop_0^\frac{\pi}{2} f(x)~dx=1$$ Here we have an important equation in physics: $$\left( i \gamma^\mu \partial_\mu - m \right) \psi = 0$$

Very long equations

If you wrote in Latex before you probably know that there are always problems with "very long" equations and this is a pain because you never know beforehand when an equation is "very long". Here this problem does not exist! Consider the following "very long equation": $$\frac{dF}{dx}\frac{dx}{dy}\frac{dy}{d\xi}=\intop_{\mathbb{R}}f(\zeta)e^{-\zeta}\cos(w^{2}-\zeta)\ d\zeta+\frac{3x^{3}+(\nabla\times\boldsymbol{E})\cdot\boldsymbol{B}}{\vec{r}\cdot\vec{E}}+8\pi\hbar+\log\cos\tan\sin\pi$$ Now reduce the width of the window in which you are reading this and see what happens when this equation becomes "very long". You can simply scrool horizontally to see it completeIf this were a PDF produced with Latex, this equation would probably be problematic by going out of the page..

Custom Latex commands

It is also possible to define custom Latex commands for the equations. Suppose you are working with quantum mechanics and you are using the bracket notation. You can define the \KET command as you would do in Latex inserting \def\KET#1{\left|#1\right\rangle } and then you can use it to write, for example, the Schrödinger equation via \hat{\mathscr{H}}\KET{\psi}=i\frac{\partial}{\partial t}\KET{\psi}. The result is: $\def\KET#1{\left|#1\right\rangle }$ $$ \hat{\mathscr{H}}\KET{\psi}=i\frac{\partial}{\partial t}\KET{\psi} $$

Floats

In Latex we have a powerful and useful resource which are the floats. A figure and a table are examples of floats. To obtain a float here we use the float tag. Within <float> and </float> you put whatever content you want and (mandatory) a caption using floatcaptionI wanted to use caption instead of floatcaption, which is more intuitive and easier, but there is some weird behavior with it in HTML and unfortunately it is not possible to use for this.. To assign the "type of float" (figure, table, video, whatever you want) you have to specify its class attribute. Whatever you assign to the class attribute will be used to create/increase a counter for such class of floats and will be displayed in the captions and cross references. See for an example.

Example of usage of float. <float class="Code" id="Code: example of float"> <floatcaption>Example of usage of <code>float</code>.</floatcaption> Put here whatever you want, an image, a code, a video, etc. </float>

Custom floats

As said before the class attribute of a float element specifies the type of float it is, e.g. a figure or a table. Nothing stops you from creating your own types of floats. For example you can create the floats of type Video or Code or whatever you want. To do this just insert a float of the class you want and it is automatically created. Simple and easyIn fact the usual float types Figure and Table are not specifically defined here, they are created on the fly just as any other type you may want to use.. Each type of float will have its own counter for numbbering them, and in the caption they will be labeled according to their class attribute.

Please note that the class attribute of a float element is case sensitive, i.e. <float class="Figure"> is different than <float class="figure">.

Floats examples

Below I left some examples of floats. All the codes, such as , are floats of class Code.

This is a float of class Figure. Note that the class is the word used to identify this type of float and automatically asign a number to it, and it is case sensitive. So a figure will be different than a Figure.

Some random text, bla bla bla.

This is a float without class. Basically it contains something (e.g. an image) with a caption that is not numbered. It cannot have a crossref pointing to it. I don't know why would someone use this, but it is possible.

More random text.

The image in this figure has undefined width and height, only the max-height and max-width properties were defined. As a consequence it automatically changes its size depending on the viewport (window) size until one of the maximum width or height is achieved. This is really useful because it should not fail in a mobile.

In you can see a view of Buenos Aires, the capital city of Argentina.

This image has the width fixed (and thus also its height). This image will not change as a function of the window size. In a mobile it may overflow.

A PDF cannot handle a plot made with plotly as the one in . This plot is interactive, you can zoom, pan, enable/disable traces, etc. This has proven to be very useful to me when showing my results to other scientists as you don't need to produce many versions of the same plot with different zooming conditions.

This plot is interactive, it was produced using the nice Python package plotly. Note that despite this float is a Figure, you can put whatever content you want inside. In this case we have an interactive snippet with a plot.

Of course we can make this plots to fill the full width of the window so they change as we reshape the window. See for example the plot in . If you change the width of this window the plot will automatically adapt itself. Cool!

Note that you can place the caption above the figure, not only below. Just place the floatcaption tag where you want the caption to be.

Another nice point of these "interactive plots" is that the font size in the legend/labels matches the font size of the document, so if you zoom in or out, or open this in a mobile, the text will render properly. Try to ctrl+wheelOr whatever command you use in your browser to change the zoom. to change the zoom of this window and see how the text and markers in these plots are modified.

The float objects can be of any class that is good for your purpose. For example see which is of class Video.

Adiós Nonino by Ástor Piazzolla, interpreted by Ayelén di Montezemolo.

Cross referencing

To insert a cross reference you have to use the crossref tag. Within this tag you have to put the id of the object you want to refer to. For example has id="my first equation". To cite this equation we proceed as shown in . crossref usage example. <p>The solution $f(x)$ to <crossref toid="my first equation"></crossref> is $f(x)=\sin(x)$.</p> The code shown in produces this: The solution $f(x)$ to is $f(x)=\sin(x)$.

We can use crossref to make reference to

The machinery implemented here automatically knows what type of object you are refering to and inserts the proper text, creates the link and the popup bubble on mouse hover.

Cross referencing sections without the need of adding an id

Since the title of a section is almost an id, you can use crossref with sections without the need of adding a specific id to the section, you can just use the title of such section. For example has no id defined, it is just <h2>Cross referencing sections without the need of adding an id</h2> and despite it has no id I can still do <crossref>Cross referencing sections without the need of adding an id</crossref> and obtain: .

Note that in this case the name of the section is used as its id so if you change the name you will broke the reference. So be careful!

Footnotes

You can add footnotes by using the footnote tag like this: <footnote>footnote content</footnote>, which whill produce this:footnote content. This is another example of footnoteThis is a footnote. We can have an equation $e^{i\pi}+1=0$.. Of course footnotes can have crossrefs within themMany times footnotes make references to equations, like equation for example.You can also place many consecutive footnotes one after the other..

If you add footnotes in your document, you must add somewhere the place where you want your footnotes to be listed and shown. In there is an example of how to do it. Note that the <h1 class="unnumbered">Footnotes</h2> element is just aesthetic, you can change it or delete it.

Example for creating the list of footnotes. You MUST have this somewhere in your document if you have inserted footnotes. <div id="footnotes_list"> <h1 class="unnumbered">Footnotes</h2> </div>

Bibliography and citations

To insert bibliography first we create create reference elements and then we cite them just using crossref in the same way as detailed in . So, for example <reference id="book Jackson Classical Electrodynamics">Jackson, J. D. (1999). Classical electrodynamics.</reference> creates a bibliography entry and then we can just use crossref with its id. Before being able to use this there is one last step which is to place our list of references. For this just create a div element with id references_list anywhere in your document (usually in the end).

A complete example for creating the bibliography is shown in . Example for creating bibliography and external references <!-- Put this wherever you want your list of references to be shown. --> <div id="references_list"> <h1 class="unnumbered">References</h1> <!-- This title is optional, it is just a decoration. --> <!-- We create the "reference" elements within the "references_list" so we keep everything together --> <reference id="book Jackson Classical Electrodynamics">Jackson, J. D. (1999). Classical electrodynamics.</reference> <reference id="paper EPR">Einstein, A., B. Podolsky, and N. Rosen. “Can Quantum-Mechanical Description of Physical Reality Be Considered Complete?” Physical Review 47, no. 10 (May 15, 1935): 777–80. <a href="https://doi.org/10.1103/PhysRev.47.777">https://doi.org/10.1103/PhysRev.47.777</a>.</reference> <reference id="paper Bell">Bell, John Stewart. “On the Einstein Podolsky Rosen Paradox” 1, no. 3 (1964): 6.</reference> </div> Now we can simply insert crossrefs to the reference elements we have defined and obtain: , and . Note that they are automatically ordered and that unused reference elements will be not displayed.

Code

To insert code we use the standard tag code. For inline code like this one just write <code>this one</code>. For non-inline code we set the class to block, see code for example.

Example of block code. <code class="block"> Put here your code </code>

By using the syntax shown in code we get, for example, the code .

This is my code for the sequencer in the FPGA for testing the TDC. `timescale 1ns/1ps module sequencer_for_TDC_V1_SW_28_10_19 ( //-------------------------------------------------------------------// // This is the sequencer module to interface with the test structure // // that I am calling "TDC_V1_SW_28_10_19" which is the one produced // // by S. Widerkehr that contains 4 TDC test structures. // //-------------------------------------------------------------------// input clk, input reset, input run_sequencer, // Setting this to 1 starts the sequencer. input [7:0]t_start_coarse, input [7:0]t_stop_coarse, output ready_flag, // 1 means that the sequencer is ready to start a new run, 0 means it is not. output reg measure_flag, // This is what Beat called "measure". output reg write, // This tells the RAM memory when to write. output reg[15:0]data, // This sends the data to the RAM memory. // TDC_V1_SW_28_10_19 test structure ---// output reg [3:0]SEL, // output reg PSTART, // output reg PSTOP, // output reg RES, // input [6:0]DOUT, // input [20:0]SAFF // // -------------------------------------// ); // State machine states --------------------------------------// localparam SM_IDLE = 5'd0; // localparam SM_WAIT_FOR_RUN_SIGNAL = 5'd1; // localparam SM_START_MEASURE_SEQUENCE = 5'd2; // localparam SM_MEASURE_SEQUENCE = 5'd3; // localparam SM_READOUT_SEQUENCE = 5'd4; // reg [4:0]current_state; // reg [4:0]previous_state; // wire state_did_not_change = previous_state == current_state; // // -----------------------------------------------------------// reg [9:0]current_state_time_count; // This counts the number of clock cycles that the state machine has been in the "current_state" state. Each time the state changes, this will be reseted to 0. assign ready_flag = (current_state == SM_WAIT_FOR_RUN_SIGNAL); always @(posedge clk or posedge reset) begin if (reset) begin current_state <= SM_IDLE; previous_state <= SM_IDLE; current_state_time_count <= 9'd0; SEL <= 4'b0000; PSTART <= 1'b0; PSTOP <= 1'b0; RES <= 1'b1; measure_flag <= 1'b0; write <= 1'b0; end else begin // if NOT reset if (state_did_not_change) begin current_state_time_count <= current_state_time_count + 9'd1; end else begin previous_state <= current_state; current_state_time_count <= 9'd0; end case (current_state) // State machine machinery --- SM_IDLE: begin SEL <= 4'b0000; PSTART <= 1'b0; PSTOP <= 1'b0; RES <= 1'b1; current_state <= SM_WAIT_FOR_RUN_SIGNAL; end SM_WAIT_FOR_RUN_SIGNAL: begin if (run_sequencer) current_state <= SM_START_MEASURE_SEQUENCE; end SM_START_MEASURE_SEQUENCE: begin measure_flag <= 1'b1; RES <= 0; // Remove the "reset" signal from the test structure. current_state <= SM_MEASURE_SEQUENCE; end SM_MEASURE_SEQUENCE: begin: measure_sequence if (current_state_time_count[7:0] == t_start_coarse) PSTART <= 1; if (current_state_time_count[7:0] >= t_stop_coarse) begin PSTOP <= 1; if (current_state_time_count[7:0] == t_stop_coarse + 2) begin // Finish the measure sequence. I am waiting some time (i.e. t_stop_coarse + something) so any transient in the test structure finishes. The sime scale in the test structure is in the order of pico seconds so a few number of clock cycles here (order nano second) should be enough. current_state <= SM_READOUT_SEQUENCE; measure_flag <= 1'b0; end/*if*/ end end/*measure_sequence*/ SM_READOUT_SEQUENCE: begin: readout_mechanism reg [2:0]write_counter; // This counter is used to write the many bytes from each TDC into the memory. if (SEL == 4'b0000) begin SEL <= 4'b0001; write_counter <= 3'b000; end else begin write_counter <= write_counter + 3'd1; case (write_counter) 0: data[15:0] <= {DOUT[6:0], 4'd0, SAFF[20:16]}; // This will be written to the memory in the base board module. 1: write <= 1'b1; // This will tell the memory block in the base board to write the data. 2: write <= 1'b0; // Disable writing. 3: data[15:0] <= SAFF[15:0]; // Select the remaining data. 4: write <= 1'b1; // Write to the memory. 5: write <= 1'b0; 6: begin SEL <= {SEL<<1}; // Move to the next TDC structure. write_counter <= 3'd0; // Reset the write counter so for the next TDC structure we repeat the cycle again. if (SEL == 4'b1000) // If we are in the last test structure... current_state <= SM_IDLE; // When the last TDC was read, we have finished. end endcase end end endcase end end endmodule

Note that code can be outside a float element, for example: This is my code I like this code This code is not inside a float element so you cannot insert a crossref to refer to this code, but you can still insert code in this way and it will be displayed cool Lalala

Acronyms (siglas)

In academia we love acronyms. I have read articles with so many acronyms that it was really hard to follow as at some point you forget what they mean.

To insert acronyms use the siglasIf you are wondering why I opted for using the Spanish word siglas for this, the reason is that acronym is already used in HTML for a similar purpose. It's usage, however, is more cumbersome and less practical, so I decided to implement my own. tag, see example in . An example of a document using siglas is shown in .

Usage example for siglas. <siglas class="definition" first="Large Hadron Collider (LHC)" short="LHC"></siglas> <!-- First we define our siglas (this can be done anywhere, there is no need to do it in the beginning of the document --> <p>This is a paragraph. This is my first mention of the <siglas>LHC</siglas>. The previous will be displayed with the "first", i.e. it will say Large Hadron Collider (LHC). The following usages, like this one <siglas>LHC</siglas> will just display LHC and the full name will be displayed on mouse hover.</p> Example of a document using siglas. Open document in new tab. Hover your mouse pointer over any acronym to display a popup message with the meaning.

Comment boxes

Sometimes there is some stuff that is a side comment, but it is too long to fit in a footnote. For those cases there is the CommentBox "environment" which is nothing more that standard HTML and pure CSS with a nice formatting. To use this you must include in your document the CommentBox.css file in the same way you include any CSS. After this you can do:

Example of CommentBox. <div class="CommentBox"> <div class="CommentBoxTitle"> Put here a nice title for this comment box </div> <div class="CommentBoxBody"> <p>Here you can write a long discussion about whatever you want, which is related with the main text but it is still a side note, but too long for a footnote. Note that you can put whatever you want inside this comment box, for example some math $$x^2 = \cos x$$ or a reference to some equation <crossref toid="very long equation"></crossref>, a float:</p> <float class="Figure"> <image style="max-width: 100%" src="https://www.planetware.com/wpimages/2019/10/switzerland-in-pictures-most-beautiful-places-matterhorn.jpg"></image> <floatcaption>A picture of the <a href="https://en.wikipedia.org/wiki/Matterhorn">Matterhorn</a>, the most famous mountain in Switzerland.</floatcaption> </float> </div> </div>

The example in will produce this:

Put here a nice title for this comment box

Here you can write a long discussion about whatever you want, which is related with the main text but it is still a side note, but too long for a footnote. Note that you can put whatever you want inside this comment box, for example some math $$x^2 = \cos x$$ or a reference to some equation , a float:

A picture of the Matterhorn, the most famous mountain in Switzerland.

References

Jackson, J. D. (1999). Classical electrodynamics. Einstein, A., B. Podolsky, and N. Rosen. “Can Quantum-Mechanical Description of Physical Reality Be Considered Complete?” Physical Review 47, no. 10 (May 15, 1935): 777–80. https://doi.org/10.1103/PhysRev.47.777. Bell, John Stewart. “On the Einstein Podolsky Rosen Paradox” 1, no. 3 (1964): 6.

Footnotes