ToriOS Manual

 

One of the important things about software development is something that is sometimes overlooked, good quality and upto date documentation.

As documentation lead for the ToriOS operating system is it my task to help develop the offline documentation.

For this I am using LaTeX which produces professional out put and is actually easier to use than trying to wrestle with software that tries to be helpful, (e.g libreoffice making anything starting http references in to hyperlinks automatically.

While LaTeX is excllent for this some of the markup for creating tables can be rather time consuming.  A few years ago Henry Brembridge who is a member of the DCGLUG told me about a program called txt2tags,  this is essentally a program that can take a text file with simple markup and convert in to a wide range of other markup files. e.g html , LaTeX, wiki etc.

Last night I had the task of re-doing the table with the information regarding the ToriOS team,  so basically creating a LaTeX table from the information on the ToriOS website so the manual was up to date.

Faced with this I could have either re-done the manual in LaTeX and probably ended up missing a tag off and then be bombarded with error messages or use txt2tags, I opted for the latter.

so I created the txt2tags source file

|| Job Title | Name | IRC Nick | E-mail |
 | Project lead | Ali Linx | amjjawad | amjjawad@torios.org |
 | Website admin | William Cornelius |  | william@torios.org |
 | Documentation - manual | Paul Sutton | zleap	zleap@torios.org |
 | Documentation - wiki | Geoffrey De Belie | smile | smile4ever@torios.org |
 | Developer lead / driver | Alexander Kluth |	DerAlex | alexander@torios.org |
 | Quality Assurance Testing | 	Jack | fjack | | 	 
 | Marketing |	David B Yentzen | | dbyentzen@torios.org |
 | Artwork | Rafael | rafaellaguna | |	
 | Developer / testing | Israel | israeldahl | israel@torios.org |

and ran this through txt2tags

txt2tags -t tex torios-team.t2t

the result was the same file all nicely formatted in LaTeX

\documentclass{article}
\usepackage{graphicx}
\usepackage{paralist} % needed for compact lists
\usepackage[normalem]{ulem} % needed by strike
\usepackage[urlcolor=blue,colorlinks=true]{hyperref}
 
\begin{document}
\maketitle
\clearpage
 
 
\begin{center}\begin{tabular}{|l|l|l|l|}
\hline \textbf{Job Title} & \textbf{Name} & \textbf{IRC Nick} & \textbf{E-mail} \\
\hline Project lead & Ali Linx & amjjawad & \htmladdnormallink{amjjawad@torios.org}{mailto:amjjawad@torios.org} \\
\hline Website admin & William Cornelius &  & \htmladdnormallink{william@torios.org}{mailto:william@torios.org} \\
\hline Documentation - manual & Paul Sutton & zleap	\htmladdnormallink{zleap@torios.org}{mailto:zleap@torios.org} \\
\hline Documentation - wiki & Geoffrey De Belie & smile & \htmladdnormallink{smile4ever@torios.org}{mailto:smile4ever@torios.org} \\
\hline Developer lead / driver & Alexander Kluth $|$	DerAlex & \htmladdnormallink{alexander@torios.org}{mailto:alexander@torios.org} \\
\hline Quality Assurance Testing & Jack & fjack & $|$ \\
\hline Marketing $|$	David B Yentzen & $|$ \htmladdnormallink{dbyentzen@torios.org}{mailto:dbyentzen@torios.org} \\
\hline Artwork & Rafael & rafaellaguna & $|$ \\
\hline Developer / testing & Israel & israeldahl & \htmladdnormallink{israel@torios.org}{mailto:israel@torios.org} \\
\hline \end{tabular}\end{center}
 
% LaTeX2e code generated by txt2tags 2.6 (http://txt2tags.org)
% cmdline: txt2tags -t tex torios-team.t2t
\end{document}

It needed some editing, as I didn’t want the table in the manual to have hyperlinsk to the e-mail addresses but it worked great,  just some editing and adding the modules at the top to the include list in the LaTeX pre-amble.

The torios manual is now up to date.

To illustrate the fact that you can have several targets here is the same output for html

txt2tags -t html torios-team.t2t

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META NAME="generator" CONTENT="http://txt2tags.org">
</HEAD><BODY BGCOLOR="white" TEXT="black">
<CENTER>
</CENTER>
 
 
<TABLE BORDER="1" CELLPADDING="4">
<TR>
<TH>Job Title</TH>
<TH>Name</TH>
<TH>IRC Nick</TH>
<TH>E-mail</TH>
</TR>
<TR>
<TD>Project lead</TD>
<TD>Ali Linx</TD>
<TD>amjjawad</TD>
<TD><A HREF="mailto:amjjawad@torios.org">amjjawad@torios.org</A></TD>
</TR>
<TR>
<TD>Website admin</TD>
<TD>William Cornelius</TD>
<TD></TD>
<TD><A HREF="mailto:william@torios.org">william@torios.org</A></TD>
</TR>
<TR>
<TD>Documentation - manual</TD>
<TD>Paul Sutton</TD>
<TD>zleap	<A HREF="mailto:zleap@torios.org">zleap@torios.org</A></TD>
</TR>
<TR>
<TD>Documentation - wiki</TD>
<TD>Geoffrey De Belie</TD>
<TD>smile</TD>
<TD><A HREF="mailto:smile4ever@torios.org">smile4ever@torios.org</A></TD>
</TR>
<TR>
<TD>Developer lead / driver</TD>
<TD>Alexander Kluth |	DerAlex</TD>
<TD><A HREF="mailto:alexander@torios.org">alexander@torios.org</A></TD>
</TR>
<TR>
<TD>Quality Assurance Testing</TD>
<TD>Jack</TD>
<TD>fjack</TD>
<TD>|</TD>
</TR>
<TR>
<TD>Marketing |	David B Yentzen</TD>
<TD>| <A HREF="mailto:dbyentzen@torios.org">dbyentzen@torios.org</A></TD>
</TR>
<TR>
<TD>Artwork</TD>
<TD>Rafael</TD>
<TD>rafaellaguna</TD>
<TD>|</TD>
</TR>
<TR>
<TD>Developer / testing</TD>
<TD>Israel</TD>
<TD>israeldahl</TD>
<TD><A HREF="mailto:israel@torios.org">israel@torios.org</A></TD>
</TR>
</TABLE>
 
<!-- html code generated by txt2tags 2.6 (http://txt2tags.org) -->
<!-- cmdline: txt2tags -t html torios-team.t2t -->
</BODY></HTML>

And you have the same content in html format.