\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_definitions}
\input{common_latex/common_latex_memo_format}
%===================================================================

\begin{document}

\begin{labcover}
\labtitle{Overview of Project-PavLab}
\vspace{0.1in}
\labdate{August 2017}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

\wikidoc{file=Memo.ProjPavlab}
\wikidoc{auth=mikerb@mit.edu}


%====================================================================
\section{Project-PavLab Overview}
%====================================================================

Project-PavLab is a repository on the oceanai server containing a
number of tools and files of use to core members of the PavLab/LAMSS
group. As a quick view it contains:

\vspace{0.1in}
\noindent
Project-PavLab Content:
\begin{packed_itemize}
\item Documentation for PavLab MOOS apps, help pages, labs, and memos.
\item Bibliography (LaTex \var{.bib}) files for PavLab research. And
  PDFs of papers.
\item PavLab software tools for documentation, biblography managment,
  and archiving.
\end{packed_itemize}

\vspace{0.1in}
\noindent
Project-PavLab Software Tools:

\begin{packed_itemize}
\item The TexWiki Toolbox for converting LaTex documents into Wiki page
  content.
\item The DULoad Toolbox for managing and archiving large sets of data
  files between the oceanai server and the local machines of users.
\item The \cmd{bibfind} utility for viewing and searching on contents
  of one or more LaTex bibliography files.
\end{packed_itemize}

\pskip

\noindent
For members and graduate students working in the lab, the intention is
that this folder is checked out on each person's machine, and each person
is familiar with the tools.

%=====================================================================
\subsection{If you're writing MOOS apps or any other software}

{\em If you are writing software in the group, you are expected to
  document your work. Not eventually document, but rather as you write
  the code.}

\vspace{0.1in}
\noindent
The form of the documentation is LaTex. And in particular a certain
basic subset of LaTex that lends itself to translation in the
\cmd{texwiki} tool. The tools and structure of \var{project-pavlab},
allow you to get started on this quickly with your documents automatically
refreshed to the lab wiki page.

\vspace{0.1in}
\noindent
    {\em Your software contribution to the group is not cemented until your
      documentation is online. Even (especially) the little tools.}

%=====================================================================
\subsection{If you're writing a thesis or publishing work in the group}

If you plan to conduct research and write papers in the group, the
project-pavlab repository is a good place to store:

\begin{packed_itemize}
\item The papers you are reading and plan to cite.
\item The BibTex file
\end{packed_itemize}

\vspace{0.1in}
\noindent
It makes perfect sense to compose your documents elsewhere, but the
bibliography information and set of papers can be a matter for the
group. By keeping papers in this repository it will facilitate group
reading and avoid duplication of effort in hunting down citation
information.

\vspace{0.1in}
\noindent
Although you compose your papers in another folder, hopefully you will
utilize a version control system. At the very least just to have your
own backup, but also to ease collaboration in the group on jointly
authored papers and thesis revisions.

%=====================================================================
\subsection{If you're involved in collecting data/media during group work}

If you plan to capture mission log files or other media, such as
videos or audio or any other files used by the group, we will do this
via the large (as of this date 40TB) drive on the oceanai server. For
this the DULoad Toolbox tools should be used, and the raw-file naming
scheme should be used.


%=====================================================================
\section{Structure of the Project-PavLab Repository}
%=====================================================================

The \var{project-pavlab} tree holds three types of content,
documentation, bibliography information, and software utilities:

\vspace{0.15in}
\begin{consoleverb}
 $ cd project-pavlab/
 $ ls
 appdocs/                <-- docs (software apps)
 helpdocs/               <-- docs (random help snippets / how-tos)
 labdocs/                <-- docs (lab exercises / training)
 memos/                  <-- docs (memos like this one)
 private_docs/           <-- docs (stuff not for sharing yet or ever)
 biblio/             <-- bibtex info and reading material
 utils/                  <-- software (texwiki, duload, bibfind)
 clean.sh*               
\end{consoleverb}
\vspace{0.15in}

%=====================================================================
\subsection{Getting the Project-PavLab Tree (With R/W Access)}

If you are part of the PavLab group with an account on the oceanai
server, you can check out the tree with:

\vspace{0.15in}
\begin{consoleverb}
 $ svn co svn+ssh://oceanai.mit.edu/svn/repos/project-pavlab
\end{consoleverb}
\vspace{0.15in}

\noindent
If you are part of LAMSS, or the Marine Robotics Group, access to
oceanai and this tree is there for the asking.  If you have trouble
checking out the tree:

\begin{packed_itemize}
\item Log on to oceanai via \cmd{ssh}. If you cannot log in, seek help.
\item After logging in, verify you belong to the \var{pavlab} group,
  by typing on the command line: \cmd{groups}. If you don't see
  \var{"pavlab"} in the list of groups for your account, then seek help.
\end{packed_itemize}

\vspace{0.15in}
\noindent
If you're able to perform the above two steps, but still cannot checkout
the \var{project-pavlab} repository, then seek help.

%=====================================================================
\subsection{Getting the Project-PavLab Tree (Anonymous Read-Only Access)}

Anonymous read-only access is available to members outside the group,
i.e., without access to the oceanai server. This form of access is
primary useful to us for auto-updating our web pages with wiki content
as the LaTex documents are checked in to the repository. In any event
it's good to know that this type of access exits:

\vspace{0.15in}
\begin{consoleverb}
 $ svn co https://oceanai.mit.edu/svn/project-pavlab-aro
\end{consoleverb}
\vspace{0.15in}

\noindent
When checked out in this manner, you will only get the below portion of
the tree:

\vspace{0.15in}
\begin{consoleverb}
 $ cd project-pavlab-aro
 $ ls
 appdocs/      
 helpdocs/
 labdocs/
 memos/
\end{consoleverb}
\vspace{0.15in}

%=====================================================================
\subsection{building the Project-PavLab Utilities}

As a lab member, you should check out the version of the tree above
with read-write access and with the \var{utils/} sub-directory. You
will need to build these utilities. These tools do link against
utilities in the \var{moos-ivp} repository, which is assumed to be 
already downloaded and built on your machine. The \var{moos-ivp} and
\var{project-pavlab} trees should be in the same folder.

\vspace{0.15in}
\begin{consoleverb}
 $ cd project-pavlab/utils
 $ ./build.sh
 $ cd bin/
 rrf.sh*        texwiki_book*    bibfind*       
 dload.pl*      texwiki*         uload.pl*
\end{consoleverb}
\vspace{0.15in}

\noindent
You should put \var{project-pavlab/utils/bin/} in your shell path.

%=====================================================================
\section{Writing documents, using LaTex and using texwiki}
%=====================================================================

We bin our document types in to four different groups:

\begin{packed_itemize}
\item {\em Applications}: these describe specific software tools,
  typically MOOS Apps, but also command line tools and other software.

\item {\em Help}: these documents are short snippets covering a wide
  variety of topics often encountered in the lab. Often these topics
  escape more formal documentation, but may nonetheless be the kind
  of knowledge repeated over and over between lab members.

\item {\em Labs}: these documents are designed to guide readers through
  a sequence of steps and exercises designed to teach or build up a
  certain skill. For example the C++ mini labs. Or other course labs.

\item {\em Memos}: All else falls in the memo category. For example this
  memo.
\end{packed_itemize}

\vspace{0.1in}
\noindent
Of course there are other categories such as thesis documents, and
conference or journal papers. But these types of documents are more
private as they progress. Typically we encourage users to write their
publications or theses in their own folders (\var{project-pavlab}
would simply get too big!). The exception is that bibliography
building is encouraged to be in the \var{project-pavlab/biblio/}
folder as described below in Section \ref{sec_pav_biblio}. And of
course finished thesis or confernce PDFs should land in the
\var{biblio} folder as well.

\vspace{0.1in}
\noindent
These four document categories, plus the private category, are aptly
named directories in project-pavlab, \var{appdocs}, \var{helpdocs},
\var{labdocs}, \var{memos}, and \var{private\_docs}.


%=====================================================================
\subsection{How to start a new document - conventions and examples}

The first step to creating a new document is to consider if this falls
in the category of documenting an {\em application}, {\em help topic},
{\em lab} or {\em memo}. It can always be changed later so don't fret if your
  document is not clearly in one of these buckets.

\vspace{0.1in}
\noindent
There is a naming convention that is important. For example, in the
\var{appdocs/} folder, an application called \app{pFooBar} would be given
a new folder named \var{app\_pfoobar}. And the LaTex main document in
this folder would be called \var{app\_pfoobar.tex}. Note the directory
name and document name are the same except for the \var{.tex}
suffix. So you will see the following structure:

\vspace{0.1in}
\begin{consoleverb}
$ cd project-pavlab/appdocs
$ ls 
  app_igpssim/
     app_igpssim.tex
  app_ijoystick/
     app_ijoystick.tex  
  app_im200
     app_im200.tex  
  app_ios5000/
     app_ios5000.tex  
  ...
\end{consoleverb}
\vspace{0.1in}

\noindent
The scripts that convert latex to wiki page content work with the
assumption of this naming convention.

\vspace{0.1in}
\noindent
A template can be used to get started. In the \var{appdocs/} folder there
is an example document, \var{app\_pexample}. You can begin by copying
this folder to create your own document. 


%=====================================================================
\subsection{Prior to texwiki - just focus on a working LaTex document}

Each document is meant to be built into both a PDF document and a wiki
page document. Initially the focus should be just on getting the
content into a buildable LaTex document. Some additional tweaking of
the LaTex source may be needed later to enable \app{texwiki} to work
since \app{texwiki} works with a subset of the full LaTex
capabilities.

\vspace{0.1in}
\noindent
Each document folder will typically contain the following:

\begin{packed_itemize}
\item A primary LaTex file, e.g., \var{app\_pexample.tex}
\item A \var{makefile}
\item A \var{figures/} subfolder if your doc has figures.
\item A \var{file.bib} file if your doc has references.
\end{packed_itemize}
\vspace{0.1in}

\noindent
Your document should build on the command line with:

\vspace{0.1in}
\begin{consoleverb}
 $ make
 $ make pdfo    <-- on MacOS it will make, and then open the doc in Preview
\end{consoleverb}
\vspace{0.1in}

\noindent
There are scripts on the pavlab webpage that will automatically
re-build your PDF and re-generate the texwiki page when you commit
changes to your document to the oceanai repository. These scripts
depend on the existence of a \var{makefile} that will build the PDF
with no arguments to \app{make}.

\vspace{0.1in}
\noindent
Initially as you are creating your document, it is {\em not} included
on the pavlab webpage. And no updates are triggered upon commits to the
repository. Turning this feature on is described below in Section
\ref{sec_pav_livedocs}.

%=====================================================================
\subsection{Preparing your document for texwiki}

The \app{texwiki} utility will convert a LaTex document into a wiki
page file. Since LaTex is huge, \app{texwiki} only works with a subset
of LaTex, but it's a fairly expressive subset. For example, this
memo document compiles both to LaTex and wiki documents.

\vspace{0.1in}
\noindent
If you'd like to check whether your document can be successfully
converted to a wiki page, you can invoke \app{texwiki} with the
\var{--dry-run} option:

\vspace{0.1in}
\begin{consoleverb}
 $ texwiki --dry-run app_pexample.tex
 PASS
\end{consoleverb}
\vspace{0.1in}

\noindent
If the result is instead \var{FAIL}, you can invoke again with the
\var{--verbose} or \var{-v} option to see the error messages.


%=====================================================================
\subsection{Going live on the pavlab web page}
\label{sec_pav_livedocs}

Once you are comfortable posting your document on the pavlab wikipage, the
following additional step must be taken. In each of the document directories,
\var{appdocs}, \var{helpdocs}, \var{labdocs}, and \var{memos}, there is a
file: \var{install.txt}. Edit this file and add the name of the document
to a new line in the file for example:

\vspace{0.1in}
\begin{consoleverb}
 $ cd project-pavlab/appdocs
 $ cat install.txt
\end{consoleverb}

\begin{fileverb}
File: install.txt
 app_ufld_flagmgr
 app_ufld_tagmgr
 app_pmapvalues
 app_ijoystick
 app_distcc
 app_im200
 app_ios5000
 app_igps_device
 app_iumodem
 app_igpssim
 app_usimm200
 app_uspeech_rec
 app_udialog_mgr
 app_newdoc           <-- Add your line here for example
\end{fileverb}
\vspace{0.1in}

\noindent
Note: the name of the main LaTex document does not need to be provided
since it is assumed that there is a \var{app\_newdoc.tex} file in the folder
ther \var{app\_newdoc}.

%=====================================================================
\section{Bibliography Development and the \app{bibfind} Utility}
\label{sec_pav_biblio}

The \app{bibfind} utility is a tool in the \var{project-pavlab/utils} folder and 
should be built and in your shell path.



\var{rm -f biblio.bib; cat ~/Research/project-pavlab/biblio/*.bib > ./biblio.bib}

%=====================================================================


\end{document}



