Developing a document class using a Writer2LaTeX-generated document as a starting point

Question

Background

My university is finally starting to become more LaTeX-aware and has developed and published a document class for theses and memoirs. This class is based on the memoir class and is now distributed as part of TeX Live 2012.

In my department, at least one professor uses LaTeX proficiently. I have started to work with this person in order to make LaTeX kown to other members of the department and, in particular, to members of the research center that employs me.

Recently, while editing a thesis, I realized that many authors working with my research center were at a loss when it came to formatting their work according to the provided guidelines. After convincing the department that providing stylesheets and precise instructions would benefit everyone involved in authoring and editing, I was then given the job of developing templates for OpenOffice/LibreOffice and Microsoft Word. I have completed this task, and I would now like to create a corresponding LaTeX document class to promote the use of LaTeX as an alternative to the current word processor > InDesign > PDF workflow.

The main question

I have an OpenDocument Text template containing all the styles that authors are likely to need during the editing process. Because there is much differentiation in terms of text body paragraphs, block quote styles and the like, producing the LaTeX class from the ODT template seems to be most practical solution, as the LaTeX template needs to contain all of the same styles as the ODT template and remain aligned with it.

I already use Writer2LaTeX to typeset all of the documents that I produce for my research center. Writer2LaTeX version 1.2 (currently in beta) generates a suitable preamble when a given document’s formatting has been correctly defined using styles exclusively as oppposed to manual formatting. I have an absolute requirement (which I think is reasonable in this day and age) that XeTeX or LuaTeX be used, because the field I work in (early modern literature) requires true Unicode support and most documents are bound to contain multiple languages (often French, English and Latin and occasionally polytonic Greek and Cyrillic-based languages). That is why I use Writer2LaTeX 1.2 with the engine set to “XeTeX”. Usually, all I need to do is add fontspec commands to the preamble and then I can typeset the document without any further intervention on the generated LaTeX.

However, for a LaTeX-based workflow, copying a Writer2LaTeX preamble just won’t do. I need to develop a genuine class. My intuition is that I could use Writer2LaTeX as a starting point and keep the same command names for my class. These commands often begin with \textStyle and other such prefixes depending on the family of the ODT style from which they were generated. In this way, the class would retain concepts and distinctions that are close to OpenDocument’s style model. What I need to know is: can I just dump a preamble containing all the style commands I need into a class file? I do not know much about class development, but something tells me that it cannot be the best practice. What is the best route? Customizing Writer2LaTeX’s output by “opening the hood” and writing additional XSLT? I admit that I have yet to learn XSLT, for one thing.

Sub-question

How can I make Writer2LaTeX’s generated preamble more readable? In general, I am aware of the fact that LaTeX commands can be split on multiple lines by placing comment characters % at the end of individual statements, but is there a caveat to this approach in some particular cases? My goal is to make the class code as readable as possible: I would like it to look a bit like CSS, which in my opinion is one of the best-looking languages out there and is a charm to write.

To sum it up: should I just make Writer2LaTeX’s output more readable and fine-tune it by adding fontspec definitions and the like, or should I take inspiration from Writer2LaTeX’s output and write my class from scratch using the standard class development tools?

Edit: Here is an example of a preamble created by Writer2LaTeX. This was generated from one of my course assignment documents. The only command I have added myself is \setmainfont{Brill}.

% This file was converted to LaTeX by Writer2LaTeX ver. 1.2
% see http://writer2latex.sourceforge.net for more info
\documentclass[letterpaper,12pt]{article}
\usepackage{amsmath,amssymb,amsfonts}
\usepackage{fontspec}
\setmainfont{Brill}
\usepackage{xunicode}
\usepackage{xltxtra}
\usepackage{polyglossia}
\setdefaultlanguage{french}
\setotherlanguage{english}
\usepackage{color}
\usepackage{fancyhdr}
\usepackage[top=3.39cm,bottom=3.39cm,left=3.39cm,right=3.39cm,nohead,includefoot,foot=1.016cm,footskip=1.524cm]{geometry}
\usepackage{array}
\usepackage{hhline}
\usepackage{hyperref}
\hypersetup{colorlinks=true, linkcolor=blue, citecolor=blue, filecolor=blue, urlcolor=blue}
% footnotes configuration
\makeatletter
\renewcommand\thefootnote{\arabic{footnote}}
\renewcommand\@makefnmark{\mbox{\textstyleFootnoteanchor{\@thefnmark}}}
\makeatother
% Text styles
\newcommand\textstyleEmphasis[1]{\textfrench{\textrm{\textit{#1}}}}
\newcommand\textstyleSuperscript[1]{\textsuperscript{#1}}
\newcommand\textstyleNumberingSymbols[1]{#1}
\newcommand\textstyleStephanusnum[1]{\textrm{\textsuperscript{#1}}}
\newcommand\textstyleFootnoteanchor[1]{\textrm{\textsuperscript{#1}}}
% Headings and outline numbering
\makeatletter
\newcommand\cssection[1]{\textfrench{#1}}
\renewcommand\section{\@startsection{section}{1}{0.0cm}{0.559cm}{0.559cm}{\normalfont\normalsize\normalcolor\fontsize{16pt}{19.2pt}\selectfont\rmfamily\mdseries\cssection}}
\newcommand\cssubsection[1]{\textfrench{#1}}
\renewcommand\subsection{\@startsection{subsection}{2}{0.0cm}{0.28cm}{0.28cm}{\normalfont\normalsize\normalcolor\fontsize{12pt}{14.4pt}\selectfont\rmfamily\mdseries\itshape\cssubsection}}
\renewcommand\@seccntformat[1]{\csname @textstyle#1\endcsname{\csname the#1\endcsname}\csname @distance#1\endcsname}
\setcounter{secnumdepth}{0}
\newcommand\@distancesection{}
\newcommand\@textstylesection[1]{#1}
\newcommand\@distancesubsection{}
\newcommand\@textstylesubsection[1]{#1}
\makeatother
\raggedbottom
% Paragraph styles
\renewcommand\familydefault{\rmdefault}
\newenvironment{stylePii}{\clearpage\setcounter{page}{1}\pagestyle{Standard}
\thispagestyle{FirstPage}
\setlength\leftskip{0cm plus 1fil}\setlength\rightskip{0cm plus 1fil}\setlength\parindent{0cm}\setlength\parfillskip{0pt}\setlength\parskip{0cm plus 1pt}\writerlistparindent\writerlistleftskip\begin{french}\leavevmode\normalfont\normalsize\normalcolor\fontsize{24pt}{28.8pt}\selectfont\writerlistlabel\ignorespaces}{\end{french}\unskip\vspace{0.559cm plus 0.0559cm}\par}
\newenvironment{styleAuthor}{\renewcommand\baselinestretch{1.25}\setlength\leftskip{0cm plus 1fil}\setlength\rightskip{0cm plus 1fil}\setlength\parindent{0cm}\setlength\parfillskip{0pt}\setlength\parskip{0cm plus 1pt}\writerlistparindent\writerlistleftskip\begin{french}\leavevmode\normalfont\normalsize\normalcolor\upshape\writerlistlabel\ignorespaces}{\end{french}\unskip\vspace{0cm plus 1pt}\par}
\newenvironment{styleDate}{\renewcommand\baselinestretch{1.25}\setlength\leftskip{0cm plus 1fil}\setlength\rightskip{0cm plus 1fil}\setlength\parindent{0cm}\setlength\parfillskip{0pt}\setlength\parskip{0cm plus 1pt}\writerlistparindent\writerlistleftskip\begin{french}\leavevmode\normalfont\normalsize\normalcolor\upshape\writerlistlabel\ignorespaces}{\end{french}\unskip\vspace{0cm plus 1pt}\par}
\newenvironment{styleTextbody}{\renewcommand\baselinestretch{1.0}\setlength\leftskip{0cm}\setlength\rightskip{0cm}\setlength\parindent{0.559cm}\setlength\parfillskip{0pt plus 1fil}\setlength\parskip{0cm plus 1pt}\writerlistparindent\writerlistleftskip\begin{french}\leavevmode\normalfont\normalsize\normalcolor\writerlistlabel\ignorespaces}{\end{french}\unskip\vspace{0cm plus 1pt}\par}
\newenvironment{styleQuotations}{\setlength\leftskip{1.131cm}\setlength\rightskip{1.131cm}\setlength\parindent{0cm}\setlength\parfillskip{0pt plus 1fil}\setlength\parskip{0.559cm plus 0.0559cm}\writerlistparindent\writerlistleftskip\begin{french}\leavevmode\normalfont\normalsize\normalcolor\writerlistlabel\ignorespaces}{\end{french}\unskip\vspace{0.559cm plus 0.0559cm}\par}
\newenvironment{stylePv}{\setlength\leftskip{0cm}\setlength\rightskip{0cm}\setlength\parindent{0cm}\setlength\parfillskip{0pt plus 1fil}\setlength\parskip{0cm plus 1pt}\writerlistparindent\writerlistleftskip\begin{french}\leavevmode\normalfont\normalsize\normalcolor\writerlistlabel\ignorespaces}{\end{french}\unskip\vspace{0cm plus 1pt}\par}
\newenvironment{stylePi}{\setlength\leftskip{1.131cm}\setlength\rightskip{1.131cm}\setlength\parindent{0cm}\setlength\parfillskip{0pt plus 1fil}\setlength\parskip{0.559cm plus 0.0559cm}\writerlistparindent\writerlistleftskip\begin{french}\leavevmode\normalfont\normalsize\normalcolor\writerlistlabel\ignorespaces}{\end{french}\unskip\vspace{0.559cm plus 0.0559cm}\par}
\newenvironment{styleCitationanglais}{\setlength\leftskip{1.131cm}\setlength\rightskip{1.131cm}\setlength\parindent{0cm}\setlength\parfillskip{0pt plus 1fil}\setlength\parskip{0.559cm plus 0.0559cm}\writerlistparindent\writerlistleftskip\begin{english}\leavevmode\normalfont\normalsize\normalcolor\writerlistlabel\ignorespaces}{\end{english}\unskip\vspace{0.559cm plus 0.0559cm}\par}
\newenvironment{styleCitationsuivant}{\setlength\leftskip{1.131cm}\setlength\rightskip{1.131cm}\setlength\parindent{0cm}\setlength\parfillskip{0pt plus 1fil}\setlength\parskip{0cm plus 1pt}\writerlistparindent\writerlistleftskip\begin{french}\leavevmode\normalfont\normalsize\normalcolor\writerlistlabel\ignorespaces}{\end{french}\unskip\vspace{0.559cm plus 0.0559cm}\par}
\newenvironment{stylePiv}{\renewcommand\baselinestretch{1.0}\setlength\leftskip{0cm}\setlength\rightskip{0cm}\setlength\parindent{0cm}\setlength\parfillskip{0pt plus 1fil}\setlength\parskip{0cm plus 1pt}\writerlistparindent\writerlistleftskip\begin{french}\leavevmode\normalfont\normalsize\normalcolor\writerlistlabel\ignorespaces}{\end{french}\unskip\vspace{0cm plus 1pt}\par}
% List styles
\newcommand\writerlistleftskip{}
\newcommand\writerlistparindent{}
\newcommand\writerlistlabel{}
\newcommand\writerlistremovelabel{\aftergroup\let\aftergroup\writerlistparindent\aftergroup\relax\aftergroup\let\aftergroup\writerlistlabel\aftergroup\relax}
\newcommand\labellistListileveli{\textstyleNumberingSymbols{•}}
\newcommand\labellistListilevelii{\textstyleNumberingSymbols{•}}
\newcommand\labellistListileveliii{\textstyleNumberingSymbols{•}}
\newcommand\labellistListileveliv{\textstyleNumberingSymbols{•}}
\newenvironment{listListileveli}{\def\writerlistleftskip{\addtolength\leftskip{0.4cm}}\def\writerlistparindent{}\def\writerlistlabel{}\def\item{\def\writerlistparindent{\setlength\parindent{-0.4cm}}\def\writerlistlabel{\makebox[0.4cm][l]{\labellistListileveli}\hspace{0cm}\writerlistremovelabel}}}{}
\newenvironment{listListilevelii}{\def\writerlistleftskip{\addtolength\leftskip{0.801cm}}\def\writerlistparindent{}\def\writerlistlabel{}\def\item{\def\writerlistparindent{\setlength\parindent{-0.4cm}}\def\writerlistlabel{\makebox[0.4cm][l]{\labellistListilevelii}\hspace{0cm}\writerlistremovelabel}}}{}
\newenvironment{listListileveliii}{\def\writerlistleftskip{\addtolength\leftskip{1.199cm}}\def\writerlistparindent{}\def\writerlistlabel{}\def\item{\def\writerlistparindent{\setlength\parindent{-0.4cm}}\def\writerlistlabel{\makebox[0.4cm][l]{\labellistListileveliii}\hspace{0cm}\writerlistremovelabel}}}{}
\newenvironment{listListileveliv}{\def\writerlistleftskip{\addtolength\leftskip{1.6cm}}\def\writerlistparindent{}\def\writerlistlabel{}\def\item{\def\writerlistparindent{\setlength\parindent{-0.4cm}}\def\writerlistlabel{\makebox[0.4cm][l]{\labellistListileveliv}\hspace{0cm}\writerlistremovelabel}}}{}
% Footnote rule
\setlength{\skip\footins}{0.119cm}
\renewcommand\footnoterule{\vspace*{-0.018cm}\setlength\leftskip{0pt}\setlength\rightskip{0pt plus 1fil}\noindent\textcolor{black}{\rule{0.25\columnwidth}{0.018cm}}\vspace*{0.101cm}}
% Pages styles
\fancypagestyle{Standard}{\fancyhf{}
  \fancyhead[L]{}
  \fancyfoot[C]{\thepage{}}
  \renewcommand\headrulewidth{0pt}
  \renewcommand\footrulewidth{0pt}
  \renewcommand\thepage{\arabic{page}}
}
\fancypagestyle{FirstPage}{\fancyhf{}
  \fancyhead[L]{}
  \fancyfoot[L]{}
  \renewcommand\headrulewidth{0pt}
  \renewcommand\footrulewidth{0pt}
  \renewcommand\thepage{\arabic{page}}
}
\pagestyle{Standard}
\sloppy
\title{Le rôle de l’harmonie et de la musique dans le Timée de Platon}
\author{}
\date{2013-02-01}

Not very clean-looking, as you can see, but I am sure that something good can come of it. The template I am working on for my research center has a similar set of styles.

Answer 1

What I need to know is: can I just dump a preamble containing all the style commands I need into a class file?

Please don't and also don't take any inspiration from Writer2LaTeX’s computer generated preamble. My suggestion is that you strengthen your knowledge of LaTeX and you develop your own class as follows.

Ensure the requirements are written down in a Style Guide.

Try to first write a Style Guide or to extend an existing one to cover all the typographical requirements of the Department. The Guide should cover such items as paragraph indentation, fonts, font sizing, bibliography and citations, footnotes, captions for figures and the like. This should act as a written specification for the development of the class.

Familiarize yourself with class writing techniques.

Second if you unfamiliar with class writing, review some existing classes. I suggest you select the standard classes which is available at ctan as classes.dtx. I also suggest you review the tufte-book class, which was written without using .dtx file. My own preference is to use the doc, docstrip method of generating the class, as this can be used to provide a user manual, as well as describe the class in a literate manner to ease future maintenance and versioning releases. The .dtx system is also flexible enough to provide ancillary classes, such for articles or in-house report. You can also have the class generate templates for beamer and handout presentations.

Start the development

Once the above are completed, you ready to start programming the class but for one last activity. You will need to define what part of a the thesis typography the users will be allowed to change. These will have to be provided as options to the class. For a thesis, you will probably want to limit this flexibility as I presume consistency is of paramount importance. You will also need to examine carefully your requirements to decide what packages you will load with the class. Once you have collected all this information, my own preference would have been to modify the existing book class rather than go for one of the more framework classes such as memoir. I find the basic book class very well structured and a great way to learn more about LaTeX class development. Your decision to go with XeLaTeX or LuaTeX is good,a although personally I would have gone for XeLaTeX. However, make your class universal by checking for the underlying engine and having fall-back code for all the different engines (see the tufte-book code for inspiration).

Versioning and Back-ups

Use Git and Github or a similar service for managing revisions and dropbox for back-ups or whatever other system you familiar with. As you will be using XeLaTeX or LuaTeX it is important to also create a repository for some of the packages that are under active development such as fontspec and its dependencies and polyglossia.

How Far to Go? Many of the framework like classes offer too much flexibility for what you need. In your case you have O N E very specific style to implement. Make your class as bullet proof as possible. I wish you good luck and leave you with Knuth's words:

First there was one user and I took a lot of time to satisfy myself. Then I had 10 users, and a whole new level of difficulties arose. Then I had a hundred users and another level of things happened. I had a thousand users, I had ten thousand each of those were special phases in the development, important. I couldn't have gone with ten thousand until I'd done it with a thousand. But each time a new wave of changes came along, the idea was to have TeX get better, and not get more diverse as it needed to handle new things.

Note: I will come back later and add a few links on some of the more technical aspects.