How To?

How to deal with the template?

The template is organized as follows:

• README.md: these instructions;

• License: terms of reuse (CC-By-4.0 license);

• Makefile: contains instructions for building the thesis output based on Pandoc framework.

  You may need to modify this Makefile to fit your needs;

• _data/: auxiliary information on/for the thesis

  Note: the basis metadata (title, authors,...) are defined in _data/variables.yml!;

• _layouts/: where is stored the modified Pandoc template;

• _md/: the (modified) markdown sources of the dissertation;

• _sass/: these are SASS partials that can be imported into your assets/scss/ files which will then be processed into CSS styles that define the styles to be used for html, epub and docbook5.

• assets/: the materials of the thesis (e.g. figures, bibliographies, css, fonts) or things planed to be published with the thesis;

  Note: the publishable stuffs are now in build/assets! while the root assets/ folder is intended to contains the necessary materials that are used to generate the publishable things.

Once a make <target> is performed, the following folders should appear:

• build/: all built stuff and mandatory materials are generated/copied in this folder.

  • build/<MAIN_DOC_BASENAME>.<target>: the single file targets, e.g. when targets are pdf, epub, docx, odt.

    If the target is html with BUILD_HTML_FORMAT = htmlsimple (ie. based solely on Pandoc).

    If the target is xml the base DocBook (v5) file is generated here.

  • build/html/:

    • If the target is html with BUILD_HTML_FORMAT = htmlulti the HTML5 files are build in this folder, e.g. for web-publications.
    • with target xml-chunk, i.e. chunk from DocBook (v5), the chunked html files are placed here;

  • build/assets/ : all publishable elements (e.g. css, bib, figures files) are copied/generated here.

    It is in this folder that the generated html files (single, multi or chunked) are searched. Similarly, the LaTeX build look for the external files in this folder (excepted the glossaries!)

  • build/tex/: the LaTeX intermediate files are placed here;

_md/ the (modified) Markdown sources folder

The (modified) markdown sources of your dissertation should be placed in the _md/ directory. The following rules are considered:

• 0X_filename.md: with X a digit, considered as contents 'front matter' of the dissertation to be placed before the main-matter, such as “Title page”, “Preface”, “Acknowledgment”…;
• [1-8]X_filename.md: the main-matter contents, classically split in parts, chapters and/or sections;
• 9X_filename.md: with X a digit, considered as contents 'back-matter' to be placed after the main matter, e.g. “Epilogue”, “References”, “Glossaries”…;

If you have a very big dissertation/book, you may have more than one X digit, but it is important to be consistent for all the filenames' definition.

Notice

At this time the 'appendices' are included in the 'main matter'. Later this should be placed in the 'back matter' to be consistent with “official” book parts layout

_data/

In the _data/ directory are placed auxiliary data for your documents:

• _data/metadata.yml: metadata for Pandoc and its filter (e.g. pandoc-citeproc and pandoc-crossref);

  Notes: as stated in Pandoc documentation metadata values specified inside the document, or from the commandline overwrite values specified with this file!

• _data/variables.yml: variable definition used by our Pandoc templates;

  Notes: as stated in Pandoc documentation the command line option overwrite values specified with this file!

• _data/macros.pp: the main PP-macros that imports all other macros' definition files w.r.t. the dialect target:

  • _data/latex.pp: macros for LaTeX and then for the pdf target;
  • _data/html.pp: macros for HTML5;
  • _data/docbook.pp: macros for DocBook;
  • _data/glossaries.pp: where terms, glossaries, acronyms… are defined.

_layouts/ the template folder

The Pandoc template files are placed in this folder for the different supported output dialect.

In _layouts/jekyll are defined the base Jekyll configuration files (_config.yml), and the base layouts for the htmlmulti output format.

build/tex/

If you want to handle the LaTeX source and its compilation process, the intermediate files, and the final LaTeX file are build there. Let's remember that the final PDF file is build from (Lua)LaTeX and placed in build/<MAIN_DOC_BASENAME>.pdf.

assets/

The role of the assets folders is twofold:

1. To be the place where publishable materials can be stored, such as
   • assets/bib/: for the BibTeX bibliography files;
   • assets/scss/: the SASS files to produce the [CSS] files.
   • assets/fonts/: for the font faces;
   • assets/media/: for the multimedia materials (i.e. images, video…);
2. To be the place where files generated for web-publications are stored, such as:
   • build/assets/css/: for the (generated) CSS styles;
   • build/assets/fig/: for the generated/optimized figures;

Obviously, some elements could be placed elsewhere (e.g. in _data/ folder), but the Makefile should be modified accordingly.