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 30 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