Skip to content

Commit 4516f66

Browse files
author
Tom Whyntie
committed
Adding initial version 1.0
1 parent 97adbe5 commit 4516f66

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+8386
-1
lines changed

‎.gitignore

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
## Markdown files (legacy).
2+
markdown/
3+
14
## Core latex/pdflatex auxiliary files:
25
*.aux
36
*.lof
@@ -17,7 +20,7 @@
1720
# these rules might exclude image files for figures etc.
1821
# *.ps
1922
# *.eps
20-
# *.pdf
23+
*.pdf
2124

2225
## Bibliography auxiliary files (bibtex/biblatex/biber):
2326
*.bbl

‎assets/images/frame.png

22.4 KB
Loading

‎bwb/before-we-begin.tex

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
\section{Before We Begin}\label{before-we-begin}
2+
3+
\begin{itemize}
4+
\tightlist
5+
\item
6+
\href{prerequisites.html}{Prerequisites}: This section gives a brief
7+
run-down of what you'll need - and what you'll need to know - before
8+
we can get started on the grid with the \emph{UserGuide};
9+
\item
10+
\href{conventions.html}{Conventions in this guide}: This section
11+
introduces some of the conventions used by the \emph{UserGuide}. A
12+
guide to the guide, if you will;
13+
\item
14+
\href{getting-help.html}{Getting help}: One of the great things about
15+
the GridPP project is the community of experts who are there support
16+
grid users. This section looks at the various ways you can get help if
17+
you get stuck, run into problems, or need advice on a grid-related
18+
issue.
19+
\end{itemize}

‎bwb/bwb.tex

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2+
\section{Before We Begin}
3+
\label{sec:bwb}
4+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
5+
6+
\begin{itemize}
7+
\tightlist
8+
\item
9+
\hyperref[sec:prerequisites]{Prerequisites}: This section gives a brief
10+
run-down of what you'll need - and what you'll need to know - before
11+
we can get started on the grid with the \emph{UserGuide};
12+
\item
13+
\hyperref[sec:conventions]{Conventions in this guide}: This section
14+
introduces some of the conventions used by the \emph{UserGuide}. A
15+
guide to the guide, if you will;
16+
\item
17+
\hyperref[sec:help]{Getting help}: One of the great things about
18+
the GridPP project is the community of experts who are there support
19+
grid users. This section looks at the various ways you can get help if
20+
you get stuck, run into problems, or need advice on a grid-related
21+
issue.
22+
\end{itemize}
23+
24+
\newpage
25+
26+
\input{bwb/prerequisites}
27+
28+
\newpage
29+
30+
\input{bwb/conventions}
31+
32+
\newpage
33+
34+
\input{bwb/help}

‎bwb/conventions.tex

+144
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
%=============================================================================
2+
\subsection{Conventions in this guide}
3+
\label{sec:conventions}
4+
%=============================================================================
5+
The conventions used in the \emph{GridPP UserGuide} are, by and large,
6+
self-explanatory. Here we'll look at a few that might not be.
7+
8+
%-----------------------------------------------------------------------------
9+
\subsection{The command line}
10+
\label{sec:the-command-line}
11+
%-----------------------------------------------------------------------------
12+
13+
Following \href{https://www.railstutorial.org}{Hartl}, we'll present
14+
command line examples using a Unix-style command line prompt (a dollar
15+
sign), as follows:
16+
17+
\begin{lstlisting}[gobble=0,numbers=none,language=bash]
18+
$ echo "Hello, MoEDAL!"
19+
Hello, MoEDAL!
20+
\end{lstlisting}
21+
22+
i.e.~you type what follows the dollar sign, and hopefully see the same
23+
(dollar sign-less) output in your terminal.
24+
25+
\begin{warningbox}{Comparing the output}
26+
\emph{Computer systems are always going to vary from machine to machine, so
27+
you may not see exactly the same output from a given command. We've
28+
tried to eliminate this as much as possible by using the CernVM (see
29+
later) but more often than not a combination of common sense and
30+
Googling the output should confirm if you're on the right track.}
31+
\end{warningbox}
32+
33+
Where possible we'll use bash environment variables to account for
34+
differences in working directories. However, if a particularly
35+
user-specific input is needed we'll use square brackets to denote parts
36+
of the command that require input specific to your circumstances. For
37+
example, when setting your working directory environment variable
38+
\texttt{WORKING\_DIR}, we'd write this:
39+
40+
41+
\begin{lstlisting}[gobble=0,numbers=none,language=bash]
42+
$ export WORKING_DIR=[Your working directory.]
43+
$ echo $WORKING_DIR
44+
[The value of $WORKING_DIR, hopefully your working directory.]
45+
\end{lstlisting}
46+
47+
which would actually be completed using:
48+
49+
\begin{lstlisting}[gobble=0,numbers=none,language=bash]
50+
$ export WORKING_DIR=/home/alovelace/grid-stuff/
51+
$ echo $WORKING_DIR
52+
/home/alovelace/grid-stuff/
53+
\end{lstlisting}
54+
55+
%-----------------------------------------------------------------------------
56+
\subsection{Code listings}
57+
\label{code-listings}
58+
%-----------------------------------------------------------------------------
59+
Generally speaking, we have tried to avoid listing large swathes of code
60+
in the \emph{UserGuide} itself - that's what GitHub is for. From
61+
time-to-time it may be useful to include a code snippet like the
62+
following:
63+
64+
\begin{lstlisting}[gobble=0,numbers=none,language=bash]
65+
#!/usr/bin/env python
66+
print("* This works!")
67+
\end{lstlisting}
68+
69+
Following \href{https://www.railstutorial.org}{Hartl}, we will use
70+
vertical dots to represent code omitted for the sake of brevity:
71+
72+
\begin{lstlisting}[gobble=0,numbers=none,language=bash]
73+
#!/usr/bin/env python
74+
75+
class GridJob:
76+
.
77+
.
78+
.
79+
def submit(self, id):
80+
self.id = id
81+
.
82+
.
83+
.
84+
\end{lstlisting}
85+
86+
These dots should not be copied into your code. Obvs.
87+
88+
%-----------------------------------------------------------------------------
89+
\subsubsection{Hints, warnings, and information}
90+
\label{hints-warnings-and-information}
91+
%-----------------------------------------------------------------------------
92+
The \emph{GridPP UserGuide}, like many instructional handbooks, uses
93+
little pop-out boxes to highlight important points throughout the text.
94+
95+
\begin{hintbox}{Hint boxes}
96+
\emph{This is a hint. Hint boxes are used for pointing out things that might
97+
be useful while carrying out the task being described (particularly
98+
where we have received user feedback on a given step!).}
99+
\end{hintbox}
100+
101+
\begin{warningbox}{Warning boxes}
102+
\emph{This is a warning. These are used to flag up potential pitfalls or
103+
issues you may need to be aware of to avoid making mistakes or doing
104+
Something Bad.}
105+
\end{warningbox}
106+
107+
\begin{infobox}{Information boxes}
108+
\emph{This is a point of information. These boxes will generally present
109+
things that may not directly relate to the topic being discussed but are
110+
nonetheless interesting.}
111+
\end{infobox}
112+
113+
%-----------------------------------------------------------------------------
114+
\subsubsection{Checklists}
115+
\label{checklists}
116+
%-----------------------------------------------------------------------------
117+
Once you've waded through the waffle associated with a given section,
118+
you'll be presented with a \textbf{checklist} section that will give you
119+
a simple, bullet-pointed list of the things you should be able to do
120+
once you've read that section. You should go through these to make sure
121+
you have done them and, more importantly, understood them. If not,
122+
re-read the section. Alternatively, you could plough on and try the
123+
tests - see below - to see if it makes more sense when you try to
124+
actually do something based on what you've just read.
125+
126+
%-----------------------------------------------------------------------------
127+
\subsection{Testing}
128+
\label{testing}
129+
%-----------------------------------------------------------------------------
130+
All well-written, well-packaged code should come complete with
131+
\textbf{unit tests}; scripts or bits of code that can be run to test
132+
whether one's software is working as expected (especially during
133+
development as changes are made and new versions are produced). We can
134+
try to emulate this approach by trying to test the success of each of
135+
the steps taken while following the instructions presented in the
136+
\emph{UserGuide}. At the end of each section you will therefore find a
137+
\textbf{Testing} page that will present a number of tasks or tests for
138+
you to complete to verify that you have followed the \emph{UserGuide}.
139+
As a rule you should not proceed to the next section until you have
140+
passed all of these tests.
141+
142+
If you're struggling, there are plenty of ways to get help and support.
143+
We'll find out more about these in the
144+
\hyperref[sec:help]{next section}.

‎bwb/help.tex

+117
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
%=============================================================================
2+
\subsection{Getting help}
3+
\label{sec:help}
4+
%=============================================================================
5+
There are many ways of getting help and support if you run into problems
6+
while working through the \emph{GridPP UserGuide}. If you don't happen
7+
to have a GridPP expert in the office down the corridor, you can try the
8+
methods described below.
9+
10+
%-----------------------------------------------------------------------------
11+
\subsubsection{Check the troubleshooting guide}
12+
\label{check-the-troubleshooting-guide}
13+
%-----------------------------------------------------------------------------
14+
15+
We've added a
16+
\hyperref[sec:troubleshooting]{short troubleshooting guide}
17+
for problems that users have come across that we
18+
know are specific to particular systems, generally raised via the
19+
\href{http://github.com/gridpp/user-guides/issues}{GitHub Issues page}.
20+
It might be worth checking here first for anything obvious.
21+
22+
%-----------------------------------------------------------------------------
23+
\subsubsection{Googling the error}
24+
\label{googling-the-error}
25+
%-----------------------------------------------------------------------------
26+
We can't possibly account for every error a user might encounter when
27+
working through the \emph{UserGuide}, so on encountering a problem your
28+
first port of call should be sticking the error message into your Search
29+
Engine of Choice.
30+
31+
\begin{infobox}{Errors on the Internet}
32+
\emph{This is actually a pretty good approach to software development in
33+
general. Thanks to vibrant, enthusastic communities like those at
34+
StackExchange many common computing gotchas have been documented and
35+
solved on the World Wide Web - so it's always worth checking!}
36+
\end{infobox}
37+
38+
%-----------------------------------------------------------------------------
39+
\subsubsection{Issue tracking via GitHub}
40+
\label{issue-tracking-via-github}
41+
%-----------------------------------------------------------------------------
42+
The easiest way to report problems, make suggestions, or submit comments
43+
about the \emph{UserGuide} is by raising an \textbf{issue} on the
44+
\emph{GridPP UserGuide}
45+
\href{http://github.com/GridPP/user-guides}{GitHub repository}. Simply
46+
log in to GitHub, visit the \emph{UserGuide}
47+
\href{https://github.com/gridpp/user-guides/issues}{issues page} and
48+
click on the \href{https://github.com/gridpp/user-guides/issues/new}{New
49+
issue} button.
50+
51+
\begin{infobox}{Submitting an issue to GitHub}
52+
\emph{Provide as much information as you can when raising an issue. You can
53+
also use the MarkDown format to create hyperlinks and add formatting to
54+
your issue.}
55+
\end{infobox}
56+
57+
We'll then have a public record of the issue which we can then aim to
58+
solve as soon as we can. It's also possible to link issues to the
59+
\href{https://help.github.com/articles/using-pull-requests/}{pull
60+
requests} that fix them.
61+
62+
\begin{infobox}{Watching GitHub repositories}
63+
\emph{Don't forget to Watch the repository too. You can do this by going to
64+
the repository, signing in with your GitHub account, and clicking on the
65+
Watch button at the top-right of the page. You'll then be kept
66+
up-to-date with issues and new versions as the UserGuide evolves over
67+
time.}
68+
\end{infobox}
69+
70+
%-----------------------------------------------------------------------------
71+
\subsubsection{Mailing lists}
72+
\label{mailing-lists}
73+
%-----------------------------------------------------------------------------
74+
A great way to tap into the expertise represented by the GridPP
75+
Collaboration is to join one of the mailing lists in the table below.
76+
You'll need a valid email address, but if you've read the
77+
\hyperref[sec:prerequisites]{prerequisites} you know that already.
78+
79+
%______________________________________________________________________________
80+
\begin{table}[htbp]
81+
\caption{\label{tab:mailinglists}The GridPP support mailing lists.}
82+
\lineup
83+
\begin{tabular}{@{}llc}
84+
\br
85+
\centre{1}{$\quad$List $\quad$} &
86+
\centre{1}{$\quad$Description $\quad$} &
87+
\centre{1}{$\quad$Subscribe $\quad$} \\
88+
\mr
89+
\texttt{GRIDPP-USERS} &
90+
A list for announcements and discussions &
91+
\href{https://www.jiscmail.ac.uk/cgi-bin/webadmin?SUBED1=GRIDPP-USERS\&A=1}{JISCMail} \\
92+
&
93+
aimed at UK Grid users. &
94+
\\
95+
\texttt{GRIDPP-SUPPORT} &
96+
A list for discussion and support &
97+
\href{https://www.jiscmail.ac.uk/cgi-bin/webadmin?SUBED1=GRIDPP-SUPPORT\&A=1}{JISCMail} \\
98+
&
99+
aimed at UK Grid users. &
100+
\\
101+
\br
102+
\end{tabular}
103+
\end{table}
104+
%______________________________________________________________________________
105+
106+
\begin{warningbox}{Using the mailing lists}
107+
\emph{These mailing lists are public, so keep it nice people!}
108+
\end{warningbox}
109+
110+
%-----------------------------------------------------------------------------
111+
\subsubsection{Contact us}
112+
\label{contact-us}
113+
%-----------------------------------------------------------------------------
114+
Finally, if none of the other methods yield results, drop us a line
115+
using the details here:
116+
117+
\href{https:///www.gridpp.ac.uk/contact/}{https:///www.gridpp.ac.uk/contact/}

0 commit comments

Comments
 (0)