Give ROPP user guides the same format as other ROM SAF documents

[Ian Culverwell]

It is apparently vital that the ROPP user guides have exactly the same format as the other ROM SAF documents. Unifying them certainly seems like an excellent use of busy people's time to me.

Attached:

• romsaf.cls = current ROPP UG class file.
• romsaf10.cls = preferred ROM SAF class file.
• romsaf_ropp_ug_utils.pdf = example ROPP UG pdf.
• romsaf_vr_1dvar_ofl_v10.pdf = example ROM SAF pdf.

Current build procedure involves typing make clean and then make from a directory like https://trac.romsaf.org/ropp/browser/ropp_doc/trunk/ropp_ug_v100/ropp_ug_utils

[Ian Culverwell]

romsaf.cls

[Ian Culverwell]

romsaf10.cls

[Ian Culverwell]

romsaf_ropp_ug_utils.pdf

[Ian Culverwell]

romsaf_vr_1dvar_ofl_v10.pdf

[warrick]

Latex log output when trying to use romsaf10.cls

[warrick]

Makefile used to build ROPP IO UG at Met Office

[warrick]

I tried replacing romsaf.cls with romsaf10.cls, but couldn't get it to build using the Makefile we use at the Met Office.

The first error in the log file is

   ! LaTeX Error: Missing \begin{document}.

Even though \begin{document} is included in romsaf_ropp_ug_io.tex

Not sure how to get this to build with romsaf10.cls

Francis

[Ian Culverwell]

Log file attached.

[Ian Culverwell]

romsaf_ropp_ug_utils_jkn.tex

[Ian Culverwell]

diff2francis

[Ian Culverwell]

Francis asked Kent about this, who replied:

If I remember correctly, Joe already changed one of the ROPP 
latex files such that it works with the new romsaf-class file.
I will ask Joe to try to explain what needs to be done.

Joe then wrote:

Dear Francis, 

I shall be happy to help you through this, it can be overcome. 

I made it work with romsaf_ropp_ug_utils.tex, to the point 
where Ian only had a few trivial corrections.

I suggest that you start with reproducing that.  

Options:
1) svn will not let me copy my local version which is not 
checked in. I can check it into the official branch but I am not 
sure whether you want that? Maybe that will be too messy since 
Ian may have introduced changes since May 9, when I worked on 
this. 

2) Otherwise I have a tar-file with the whole thing, I think 
Ian had a problem with tar.

3) Third and maybe most instructive, after all, step by step  
option: Take the attached tex-file and do a

meld romsaf_ropp_ug_utils_jkn.tex romsaf_ropp_ug_utils.tex 

(that will take you through the changes which has to be done
for all the ug..tex files)

In a addition to that you will have to convert all the figures 
from eps to pdf. I would try to do that with a bash command 
line, but it depends a little on how you usually work.

At this point I would try to do the tex'ing:

pdflatex romsaf_ropp_ug_utils 
pdflatex romsaf_ropp_ug_utils
bibtex romsaf_ropp_ug_utils
pdflatex romsaf_ropp_ug_utils

You will get an error because there are a few (less than 
handful) of things that need to be done in some assisting 
files. I just took those one by one, but you can also look in 
the attached diff2francis, which is the output of "svn diff" on 
my laptop, which should tell all the changes (I did the svn 
diff after svn up, but still there are some text-chunks that 
apparently have been moved around. I do not recall why)

You may also be prompted for some .sty -files, these are all in 
the tex-live packages. Just install all those (eq. tex-live-
latex)

These are the ingredients. Do NOT hesitate from asking 
questions, it is not as nice and smooth as it could be, it was 
just a prototype. Let us make this work.

joe

diff2francis and romsaf_ropp_ug_utils_jkn.tex attached.

[warrick]

I've attached the log from trying these instructions.

I did the meld, then ran pdflatex.

I produces a pdf but with lots of errors (some due to me not converting the plots to PDF properly)

[Ian Culverwell]

The ROPP documents, like ropp_doc/trunk/ropp_ug_v110/common/romsaf_definitions.tex should be aligned to the general ROM SAF documents, like the class sheet at ​https://svn.romsaf.org/ropp/ropp_src/branches/dev/Share/LaTeXTools/LaTeX_tools051/texmf/tex/latex/romsaf10.cls. This ticket is a suitable place to log the work.

[Ian Culverwell]

ROPP-11 DRR reviewer Axel von Engeln (EUM) says

Was actually looking for a reference quoted in the text (ROM 
SAF, 2021a) and found initially other references, e.g. [RD.2a], 
which are given in the document. Within the text, there are 
references like "(see Sec 4.8 of ROPP FM User Guide (2021a))". 
Now these seem to point to 2021a for the FM, not the 1DVar, but 
at other parts of the text, it states "1D–Var (ROM SAF, 2021a)" 
and the FM is 2021c. And is "(ROM SAF, 2021b)" pointing to the 
netCDF file or the application module, as given in the intro?

My reply:

I don't know what to do about this. It's usual for all ROM SAF 
documents to begin with a section containing

1 Introduction
1.1 Purpose and scope of this document
1.2 Applicable and reference documents
1.2.1 Applicable documents
1.2.2 Reference documents
1.3 Acronyms and abbreviations
1.4 Definitions, levels and types
1.5 Overview of this document

and I suspect the Project Manager would like to keep it that 
way.  But currently these reference documents, which (again, by 
tradition) are called RD.X, only refer to the introductory 
section.  In fact each chapter of the user guide has its own 
set of references.  Thus, for example, (ROM SAF, 2021a) might 
refer to the FM UG in one chapter and the 1DVAR UG in another.  
In the bibtex file the references appear as

...
@Misc{romsaf_fm_ug,
Author         = {{ROM} {SAF}},
Title          = {The {R}adio {O}ccultation {P}rocessing {P}ackage ({ROPP}) {F}orward model module {U}ser {G}uide},
HowPublished   = {SAF/ROM/METO/UG/ROPP/006, Version 11.0},
month          = {31 } # dec,
year           = 2021
}

@Misc{romsaf_1dvar_ug,
Author         = {{ROM} {SAF}},
Title          = {The {R}adio {O}ccultation {P}rocessing {P}ackage ({ROPP}) {1D}--{V}ar module {U}ser {G}uide},
HowPublished   = {SAF/ROM/METO/UG/ROPP/007, Version 11.0},
month          = {31 } # dec,
year           = 2021
}
...

and we simply call \citep{romsaf_fm_ug} or 
\citep{romsaf_1dvar_ug} in the latex file to cite them.  Some 
LaTeX magic that I don't understand then adds "a", "b", "c" ... 
to the date of 2021, to discriminate between the 1st, 2nd, 3rd 
... new citations.  I don't know how to change this.

I think I looked before into the possibility of providing a 
single set of references for the whole User Guide, but I seem 
to remember it didn't end happily.  I could try again.  Can we 
discuss?

Regarding your last point: I have replaced

"is a ROPP netCDF file (ROM SAF, 2021b)"

by

"is a netCDF file in ROPP format (ROM SAF, 2021b)"

(3 times) at r6976.  As you will appreciate from the above 
discussion, in chapters 4, 5 and 6 of the 1DVar UG, (ROM SAF, 
2021b) actually refers to the IO UG.

I had another try at fixing this.

If I just comment out

%\bibliographystyle{romsaf}
%\bibliography{meteorology,rom_saf}

from ug_ropp_intro.tex, it complains that

LaTeX Warning: There were undefined references.


LaTeX Warning: Label(s) may have changed. Rerun to get cross-
references right.

 )
(\end occurred inside a group at level 2)

### semi simple group (level 2) entered at line 182 (\begingroup)
### semi simple group (level 1) entered at line 168 (\begingroup)
### bottom level
(see the transcript file for additional information)
Output written on romsaf_ropp_ug_1dvar.dvi (144 pages, 545864
bytes).
Transcript written on romsaf_ropp_ug_1dvar.log.
bibtex ug_ropp_intro
This is BibTeX, Version 0.99d (TeX Live 2017)
The top-level auxiliary file: ug_ropp_intro.aux
I found no \bibdata command---while reading file ug_ropp_intro.aux
I found no \bibstyle command---while reading file ug_ropp_intro.aux
(There were 2 error messages)
make: *** [romsaf_ropp_ug_1dvar.dvi] Error 2

The top-level auxiliary file: ug_ropp_intro.aux
I found no \bibdata command---while reading file ug_ropp_intro.aux
I found no \bibstyle command---while reading file ug_ropp_intro.aux

I wonder if this is because it is a LaTeX chapter, rather than a section? If I comment out

	bibtex ug_ropp_intro

from the Makefile, it doesn't fail, but I just get "?" rather than references. So still NBG.

I can't fix this now, but at least it's now on the record.

[Ian Culverwell]

One for ROPP-12.0, where it will be raised at the DRR, so make it high priority.