1. Requirement

  • You need a google account to work with GoogleDocs

2. Get Started

  1. Create a new document in GoogleDocs https://docs.google.com/

  2. Share the document with docs.iac.ethz.ch@gmail.com

  3. Go to https://docs.iac.ethz.ch and type in the ID of your GoogleDocs document

  4. As a starting point check out the source code of this document

The ID of your GoogleDocs document (a random 45 characters long string) is encoded into the URL: https://docs.google.com/document/d/1LAY60C4Dy0EzetXDEjPav9axy6JpQOey3pXTJa1IYag/
The converter on the server runs every 5 minutes. Therefore your changes are not immediately visible!

3. Write AsciiDoc for AsciiDoctor

Not all AsciiDoc features are supported by AsciiDoctor

4. Images

  • Remote images can be included with a link

image::https://asciidoctor.org/images/octocat.jpg[GitHub mascot]

  • Alternatively, images can be uploaded over FTP. You find your link in the form of ftp://username:password@docs.iac.ethz.ch here https://docs.iac.ethz.ch/google/<YOUR_ID>/. The files will be uploaded in a folder called upload. Therefore you have to include upload in the path

image::upload/sunset.jpg[Image of a Sunset]
See https://docs.asciidoctor.org/asciidoc/latest/macros/images for more info

Directly supported are jpg and png-images. In case you upload ps, eps or pdf-images, they will be converted to png-images. Therefore you have to refer to the png-image in your asciidoc. For example, if you upload figure.ps write

image::upload/figure.png[]
Supported image formats are png, jpg, ps, eps and pdf.

5. Formulas

  • latexmath or stem is supported

latexmath:[a^2+b^2=c^2]
stem:[sqrt(4) = 2]

6. Include Documents

In order to include another document use the META-tag include

//META:include <ID>

where <ID> is the google ID of the included document.

7. References

Adding references from a bibtex file to an asciidoc file can be done using the META-tag bib

//META:bib <ID> [<style>]

Some examples:

//META:bib 1jovOEkAc-pp5ngvhl7msCxk6YS5HzBqe-ujRYnhoydd
//META:bib 1jovOEkAc-pp5ngvhl7msCxk6YS5HzBqe-ujRYnhoydd apa 
[bibliography]

8. Numbering

  • Chapters respectively sections will be automatically numbered if you add to your document the line

:numbered:

  • Tables and figures will be automatically numbered if you use META tag num and placeholders #numtab and #numfig. Add to your document the line

//META:num <offset>

  • Per default offset is equal 0, i.e. the first chapter will be chapter 1. If needed, you can define an offset. For example, with offset -1 the first chapter will be chapter 0.

  • Numbering of figures with #numfig: All #numfig will be replaced by continuous numbers. For example

[[fig-name, Figure #numfig]]
image::upload/figure.png[caption="Figure #numfig. ",title="My figure"]

Referring to figure 'fig-name' can be done like that:

For more information see <<fig-name>>.

  • Numbering of tables with #numtab works the same way.

9. Summary

Using the META-tag summary will create a summary of your document in a separate file (html and pdf). All paragraphs between

.Summary
****
text .. text
text .. text
****

will be collected and merged into the summary. The META-tags are

//META:summary
//META:summaryhead <ID>
//META:summarytail <ID>

The document defined after summaryhead will be added at the beginning of the summary. The document defined after summarytail will be appended to the summary.

10. PDF Options

  • To add a header to your PDF use the META-tag pdfheader

//META:pdfheader This is my PDF header

11. Debugging

12. Behind the Scenes