Blame Manual/repository-latex/Concepts/manuals.tex

4c79b5
% Part   : Concepts
4c79b5
% Chapter: Manuals
4c79b5
% ------------------------------------------------------------
4c79b5
% $Id: manuals.tex 6191 2010-08-02 02:36:14Z al $
4c79b5
% ------------------------------------------------------------
4c79b5
4c79b5
\begin{description}
4c79b5
\item[framework:] trunk/Manuals/
4c79b5
\end{description}
4c79b5
4c79b5
\noindent This chapter describes the CentOS Artwork Repository User
4c79b5
Guide.  The CentOS Artwork Repository User Guide is the book you are
4c79b5
reading right now. The main goals of this book is helping you to
4c79b5
understand how CentOS Artwork Repository works, and what you can do to
4c79b5
get the best of it.  It is also an excuse for you to join us and help
4c79b5
improving it.
4c79b5
4c79b5
\section{Structure}
4c79b5
4c79b5
Inside CentOS Artwork Repository, documentation is conceived using
4c79b5
\LaTeX's book class. Instead of having the entire document in a single
4c79b5
file, information has been spread in separated files under Manuals
4c79b5
framework structure. The Manuals framework structure is illustrated in
4c79b5
\autoref{fig:Concepts:Manuals:Structure} and described in
4c79b5
``\hyperlink{sec:Concepts:Manuals:Files}{Relevant Files}'' (see
4c79b5
\autoref{sec:Concepts:Manuals:Files}) and
4c79b5
``\hyperlink{sec:Concepts:Manuals:Directories}{Relevant Directories}''
4c79b5
(see \autoref{sec:Concepts:Manuals:Directories}).
4c79b5
4c79b5
\begin{figure}[!hbp]
4c79b5
\hrulefill
4c79b5
\begin{verbatim}
4c79b5
trunk/Manuals/
4c79b5
|-- Concepts
4c79b5
|   |-- CentOS
4c79b5
|   |-- Frameworks
4c79b5
|   |-- Identity
4c79b5
|   `-- ...
4c79b5
|-- Distribution
4c79b5
|   |-- Anaconda
4c79b5
|   |   |-- Firstboot
4c79b5
|   |   |-- Header
4c79b5
|   |   |-- Progress
4c79b5
|   |   `-- ...
4c79b5
|   |-- Backgrounds
4c79b5
|   |-- BootUp
4c79b5
|   |   |-- GDM
4c79b5
|   |   |-- GRUB
4c79b5
|   |   `-- ...
4c79b5
|   `-- Release
4c79b5
|-- Licenses
4c79b5
|-- Translations
4c79b5
|-- Workstation
4c79b5
|-- convenctions.tex
4c79b5
|-- repository.aux
4c79b5
|-- repository.lof
4c79b5
|-- repository.log
4c79b5
|-- repository.lot
4c79b5
|-- repository.out
4c79b5
|-- repository.pdf
4c79b5
|-- repository.tex
4c79b5
`-- repository.toc
4c79b5
\end{verbatim}
4c79b5
\hrulefill
4c79b5
\caption{Manuals framework structure.%
4c79b5
   \label{fig:Concepts:Manuals:Structure}}
4c79b5
\end{figure}
4c79b5
4c79b5
\section{Writing Style}
4c79b5
4c79b5
When writing for CentOS Artwork Repository User Guide, keep in mind
4c79b5
the following quote taken from the online ``BBC News Styleguide'':
4c79b5
---The key to good writing is \textbf{simple thoughts simply
4c79b5
expressed}.  Use short sentences and short words.  Anything which is
4c79b5
confused, complicated, poorly written or capable of being
4c79b5
misunderstood risks losing the listener or viewer, and once you have
4c79b5
done that, you might just as well not have come to work---.
4c79b5
4c79b5
If you need to express complicated ideas, try to split them out in
4c79b5
smaller and simpler ideas as much as possible. If you consider it
4c79b5
appropriate, try to use
4c79b5
``\hyperlink{sec:Concepts:Identity:Models}{Design Models}'' (see
4c79b5
\autoref{sec:Concepts:Identity:Models}) to illustrate your thoughts.
4c79b5
4c79b5
\subsection{Cross References}
4c79b5
4c79b5
When you create \LaTeX's cross references, you need to define targets
4c79b5
and links.  Targets are the specific locations in the document that
4c79b5
links point to.  In \LaTeX, these cross reference targets and links
4c79b5
can be defined in many ways, so we need to standardize the way we use
4c79b5
inside CentOS Artwork Repository User Guide to make it look uniform
4c79b5
and easy to read.
4c79b5
4c79b5
Inside CentOS Artwork Repository User Guide, cross references look
4c79b5
like illustrated in
4c79b5
\autoref{fig:Concepts:Manuals:CrossRef:Presentation}.  Cross reference
4c79b5
targets are defined as illustrated in
4c79b5
\autoref{fig:Concepts:Manuals:CrossRef:Targets}, and links to those
4c79b5
targets are defined as illustrated in
4c79b5
\autoref{fig:Concepts:Manuals:CrossRef:Links}. 
4c79b5
4c79b5
Note that we use both \texttt{hypertarget} and \texttt{label} commands
4c79b5
to define targets, and \texttt{hyperlink} and \texttt{autoref} to
4c79b5
define links.  With \texttt{hyperlink} we create long text links
4c79b5
---usefull when reading in the coputer---, and with \texttt{autoref}
4c79b5
we create numbered links ---usefull when reading in a printed copy---.
4c79b5
4c79b5
\begin{figure}[!hbp]
4c79b5
\hrulefill
4c79b5
\begin{flushleft}
4c79b5
\dots you can find more information in
4c79b5
``\hyperlink{sec:Concepts:Identity:Brands}{Logos}'' (see
4c79b5
\autoref{sec:Concepts:Identity:Brands}), specifically in
4c79b5
\hyperlink{sec:Concepts:Identity:Brands:Logos}{the horizontal version} (see
4c79b5
\autoref{sec:Concepts:Identity:Brands:Logos}).
4c79b5
\end{flushleft}
4c79b5
\hrulefill
4c79b5
\caption{Cross reference link presentation.%
4c79b5
   \label{fig:Concepts:Manuals:CrossRef:Presentation}}
4c79b5
\end{figure}
4c79b5
4c79b5
\begin{figure}[!hbp]
4c79b5
\hrulefill
4c79b5
\begin{verbatim}
4c79b5
\part{Concepts}
4c79b5
...
4c79b5
\chapter{The CentOS Logo}
4c79b5
\hypertarget{sec:Concepts:Logo}{}
4c79b5
\label{sec:Concepts:Logo}
4c79b5
...
4c79b5
\section{Horizontal}
4c79b5
\hypertarget{sec:Concepts:Identity:Brands}{}
4c79b5
\label{sec:Concepts:Identity:Brands}
4c79b5
...
4c79b5
\end{verbatim}
4c79b5
\hrulefill
4c79b5
\caption{\LaTeX's definition for cross reference targets.%
4c79b5
   \label{fig:Concepts:Manuals:CrossRef:Targets}}
4c79b5
\end{figure}
4c79b5
4c79b5
\begin{figure}[!hbp]
4c79b5
\hrulefill
4c79b5
\begin{verbatim}
4c79b5
\dots you can find more information in
4c79b5
``\hyperlink{sec:Concepts:Identity:Brands}{The CentOS Logo}'' 
4c79b5
(see \autoref{sec:Concepts:Identity:Brands}), specifically in
4c79b5
\hyperlink{sec:Concepts:Identity:Brands:Logos}{the horizontal version} 
4c79b5
(see \autoref{sec:Concepts:Identity:Brands:Logos}).
4c79b5
\end{verbatim}
4c79b5
\hrulefill
4c79b5
\caption{\LaTeX's definition for cross reference links.%
4c79b5
   \label{fig:Concepts:Manuals:CrossRef:Links}}
4c79b5
\end{figure}
4c79b5
4c79b5
\subsection{Figures}
4c79b5
4c79b5
Inside CentOS Artwork Repository User Guide, illustrations (i.e.
4c79b5
images, framework structures, source code, commands, etc.) are shown
4c79b5
using \LaTeX's \texttt{figure} environment. An example of
4c79b5
\texttt{figure} environment definition is illustrated in
4c79b5
\autoref{fig:Concepts:Manuals:Figures}.  More information about
4c79b5
\LaTeX's \texttt{figure} environment can be found in \LaTeX's info
4c79b5
manual. To read the \LaTeX's info manual, execute in your terminal the
4c79b5
command: \texttt{info latex}.
4c79b5
4c79b5
\begin{figure}[!hbp]
4c79b5
\hrulefill
4c79b5
\begin{verbatim}
4c79b5
\begin{figure}[!hbp]
4c79b5
\hrulefill
4c79b5
...
4c79b5
\hrulefill
4c79b5
\caption{... .%
4c79b5
   \label{fig:...}}
4c79b5
\end{figure}
4c79b5
\end{verbatim}
4c79b5
\hrulefill
4c79b5
\caption{\LaTeX's definition for \texttt{figure} environment.%
4c79b5
   \label{fig:Concepts:Manuals:Figures}}
4c79b5
\end{figure}
4c79b5
4c79b5
\subsection{Tables}
4c79b5
4c79b5
Inside CentOS Artwork Repository User Guide, tabular information (i.e.
4c79b5
translation markers, etc.) is shown using \LaTeX's \texttt{table}
4c79b5
environment. An example of \texttt{table} environment definition is
4c79b5
illustrated in \autoref{fig:Concepts:Manuals:Tables}.  More
4c79b5
information about \LaTeX's \texttt{table} environment can be found in
4c79b5
\LaTeX's info manual. To read the \LaTeX's info manual, execute in
4c79b5
your terminal the command: \texttt{info latex}.
4c79b5
4c79b5
\begin{figure}[!hbp]
4c79b5
\hrulefill
4c79b5
\begin{verbatim}
4c79b5
\begin{table}[!hbp]
4c79b5
\centering
4c79b5
\begin{tabular}[pos]{cols}
4c79b5
\hline
4c79b5
...
4c79b5
\hline
4c79b5
\end{tabular}
4c79b5
\caption{... .%
4c79b5
   \label{tab:...}}
4c79b5
\end{table}
4c79b5
\end{verbatim}
4c79b5
\hrulefill
4c79b5
\caption{\LaTeX's definition for \texttt{table} environment.%
4c79b5
   \label{fig:Concepts:Manuals:Tables}}
4c79b5
\end{figure}
4c79b5
4c79b5
\section{Relevant Files}
4c79b5
\hypertarget{sec:Concepts:Manuals:Files}{}
4c79b5
\label{sec:Concepts:Manuals:Files}
4c79b5
4c79b5
\subsection{repository.tex}
4c79b5
4c79b5
The \texttt{repository.tex} file is the main book's file. Here is
4c79b5
where you define specific book information like class, title, authors,
4c79b5
etc.  Inside \texttt{repository.tex} you organize chapters and load
4c79b5
their sections.
4c79b5
4c79b5
\subsection{introduction.tex} 
4c79b5
4c79b5
The \texttt{Introduction.tex} file introduces a specific artwork
4c79b5
component: what it does, where and when it appears in, etc.
4c79b5
4c79b5
\subsection{framework.tex} 
4c79b5
4c79b5
The \texttt{rramework.tex} file describes how to interact with a
4c79b5
specific artwork component: where to find the artwork component inside
4c79b5
CentOS Artwork Repository, how to render their images, how to render
4c79b5
their translations, their specific translation markers, etc.
4c79b5
4c79b5
\subsection{rebranding.tex} 
4c79b5
4c79b5
The \texttt{rebranding.tex} file describes how to rebrand a specific
4c79b5
artwork component: where to find the arwork component inside CentOS
4c79b5
Distribution, related packages you need to modify, etc.
4c79b5
4c79b5
\section{Relevant Directories}
4c79b5
\hypertarget{sec:Concepts:Manuals:Directories}{}
4c79b5
\label{sec:Concepts:Manuals:Directories}
4c79b5
4c79b5
\subsection{Concepts}
4c79b5
4c79b5
The \texttt{Concepts} directory organizes chapters related to
4c79b5
``Concepts'' part.  Files in this directory describe concepts used
4c79b5
inside CentOS Artwork Repository.
4c79b5
4c79b5
\subsection{Workstation} 
4c79b5
4c79b5
The \texttt{Workstation} directory organizes chapters related to
4c79b5
``Preparing Your Workstation'' part. Files in this directory describe
4c79b5
actions (i.e. installation and configuration) you need to do before
4c79b5
using CentOS Artwork Repository. 
4c79b5
4c79b5
\subsection{Distribution} 
4c79b5
4c79b5
The \texttt{Distribution} directory organizes chapters releated to
4c79b5
``Distribution'' part. This part gets its attention into the different
4c79b5
artwork components of CentOS Distribution, using a subdirectory
4c79b5
structure to organize them and the files \texttt{introduction.tex},
4c79b5
\texttt{framework.tex}, and \texttt{rebranding.tex} to describe them.
4c79b5
4c79b5
\subsection{Licenses} 
4c79b5
4c79b5
The \texttt{Licenses} directory organizes licenses used in this book.
4c79b5
4c79b5
\section{Revisions}
4c79b5
\hypertarget{sec:Concepts:Manuals:Revisions}{}
4c79b5
\label{sec:Concepts:Manuals:Revisions}
4c79b5
4c79b5
Revisions are a way of organizing changes committed to CentOS Artwork
4c79b5
Repository User Guide. Revisions have the format ``Revision M.N'',
4c79b5
where M is the major revision number, and N is the update revision
4c79b5
number.  Revision update number (N) may increase by one every month to
4c79b5
release that month's changes.  Once the six month cycle is reached,
4c79b5
major revision number (M) is increased by one and update revision
4c79b5
number (N) is reset to 0.
4c79b5
4c79b5
\section{Export to PDF}
4c79b5
4c79b5
To produce the file \texttt{repository.pdf}, you need to get inside
4c79b5
the Manual's framework and execute the command:
4c79b5
4c79b5
\begin{quote}
4c79b5
\texttt{pdflatex repository.tex}
4c79b5
\end{quote}