[Qgis-community-team] Re: latex coding practices

[Gary Sherman]

On May 6, 2008, at 7:44 PM, Tara Athan wrote:
> OK, I was able to download the latex version of the manual and take  
> a quick look through the various sections.
> What I see is a lot of inconsistency in format between sections.
> This is to be expected, I guess, if the sections are written by  
> different authors and there is no agreement beforehand as to format.

The manual has evolved over time with a number of authors working at  
different times so just like any "code base" you'll find these types  
of things.

> But I think we need to aim for greater consistency for the 1.0  
> manual release.
> For a start, I would like to have macros for inline styles to  
> distinguish command line inputs, file names, buttons and so on.
> I see this done frequently in software manuals-  there is a  
> different style of type for each category, and these are clearly  
> spelled out in the introduction.
>
> At present there is a wide variety of formats being used.  \textsl  
> is used for a lot of different things, so it is not obvious when you  
> see text formated as \textsl what it corresponds to. And the same  
> type of item, such as an input field selection, is sometimes  
> \textsl, sometimes in quotes, sometimes \textbf, ...
>
Rather than choosing a specific markup such as \textsl for an item, I  
would suggest using new commands to provide a layer of abstraction.  
This way you can simply modify the command definition to change all  
occurences of, for example, a tool button.

Here are the commands I used in the FOSS4G2007 QGIS workshop document:

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% my commands
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newcommand{\button}[1] 
{\cornersize{0.1}\ovalbox{\textsf{\scriptsize#1}}}
\newcommand{\classname}[1]{\textsf{\textbf{#1}}}
\newcommand{\fieldname}[1]{\textsl{#1}}
\renewcommand{\filename}[1]{\texttt{#1}}
\newcommand{\keystroke}[1]{\fbox{\textsf{\scriptsize#1}}}
\newcommand{\menuopt}[1]{\textsf{#1}}
\newcommand{\method}[1]{\textsf{\textit{#1}}}
\newcommand{\server}[1]{\textit{#1}}
\newcommand{\sqltable}[1]{\textsf{\textbf{#1}}}
\newcommand{\toolbtn}[1]{\cornersize{7mm} 
\Ovalbox{\textsf{\scriptsize#1}}}
\newcommand{\usertext}[1]{\texttt{#1}}

So you would markup a tool button like this: \toolbtn{Add Vector Layer}

This in turn is converted according to the command definition,  
resulting in an oval outline of the text in sans-serif scriptsize font.

Of course you can tweak the commands as the team sees fit. The obvious  
advantage is you can consistently apply the same markup to the same  
items and easily change the style at any time by editing the commands  
in the preamble of the document.

-gary

-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-
Gary Sherman
Chair, QGIS Project Steering Committee
-Micro Resources: http://mrcc.com
   *Geospatial Hosting
   *Web Site Hosting
-Desktop GIS Book:
   *http://desktopgisbook.com
"We work virtually everywhere"
-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-