forked from cgrandin/csas-latex
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADresDocTemplate.txt
255 lines (184 loc) · 13.8 KB
/
READresDocTemplate.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
READresDocTemplate.txt - template for Latex Res Doc. Andrew Edwards.
Thanks to Rowan Haigh and Jaclyn Cleary for various help along the
way. [email protected]. 28th April 2014.
This is a guide to getting Latex-produced documents published by CSAS.
My files aren't completely 'cleaned up', but the example should run.
There are some commented parts that I've left in in case they're
useful (or I'm not sure if I can completely delete them).
There are some packages that need to be included (though some
will just be specific to our assessment, so you could try
commenting some out if necessary).
Contents of this file:
1. How to write a Working Paper (for review at a CSAS meeting) in latex.
2. How to finalise the Reseach Document.
3. How to make the final .pdf Web Accessible.
4. List of files in this directory.
HOW TO WRITE A WORKING PAPER (FOR REVIEW AT A CSAS MEETING) IN LATEX
********************************************************************
[Fuller descriptions of the files are given below.]
1. Start with POP3CDexample.tex as a template. It should run okay (as
long as the mainDoc/ folders are there, as they should be if you you just
unzip the .7z file).
2. The resDocSty.sty file deals with the formatting to satisfy the CSAS
requirements. The requirements change each year, so this may need to be
updated.
3. The resDoc.bst file deals with formatting the bibliography. See below
for details regarding the ordering of multi-author papers (I ended up
manually doing that rather than figure it out in the .bst file).
4. The preamble (first 6 pages: title page etc., before the text starts)
needs to be in
Word - cover page is too hard to replicate in Latex, and CSAS will give the
French translations. For submitting the Working Paper (to be peer-reviewed)
you could either stick with the dummy title page etc. in the latex version,
or replace it with the Word version. So make a .pdf from the latex and a .pdf
from the .doc, and just replace the relevant latex .pdf pages (the preamble)
with the relevant Word .pdf pages. For the Working Paper you
may want to keep the Latex Table of Contents etc., and you won't have a French
resume anyway yet.
5. So, for peer review submit a .pdf. It doesn't need to be Web Accessible etc.
HOW TO FINALISE THE RESEARCH DOCUMENT
*************************************
1. Revise the text etc. due to reviewers' comments; finalise it all. IF you
can get latex to automatically add "alternate text" for figures and tables,
then do so (and let me know!). We haven't looked into it at all, but I'm
sure somebody's done that. This will save time at a later stage.
Make a .pdf of it all. We had one Appendix in Word still (which was a pain)
and so had to do some manual stitching together.
2. Edit the Word file (POP3CDresDocPreamble.doc, or latest version from
local CSAS office as it seems to change annually), though you won't have
French yet. I did the Word Table of Contents manually, based on the automated
Latex one.
3. Make a .pdf of all your Latex, and a .pdf of the Preamble, and replace
the latex preamble pages with the correct Word version.
4. Get local CSAS office to check formatting is okay; it won't be Web Accessible.
5. Send to CSAS in Ottawa so they can edit the Preamble Word file, with French
translations, document numbers and date of publication. Note that they now
put a month of publication on the front page (and there's a three-week delay
as things have to go through a high-level Ottawa office for final sign
off). So you need sufficient time to do the Web Accessibility stuff.
6. Get the Word preamble back from Ottawa. Then you can stitch that together
with your Latex .pdf file.
7. So you have a complete finalised document, which now needs to be made 'Web
Accessible'......
HOW TO MAKE THE FINAL .pdf WEB ACCESSIBLE
*****************************************
There ar no guarantees on my advice, but this seemed to get there in the end. It took me a while to figure out the steps (and I don't claim to fully understand it all), but my two Res Docs (2013/092 and 2013/093) were accepted and published by CSAS in March 2014. Once I'd got the first one approved and kept track of the steps, I think the second one took only 2 hours to make web accessible.
1. So if you had done your Res Doc in Word, your CSAS office would do this stage.
But of course you'd still be manually inserting figures into your Word file ;)
Through trial and error I figured out the following, which will hopefully work
for you. Remember, it's still better than someone messing up all your equations
in a 100+ page Word file, which has happened in the past.
2. Web accessibility, as far as I can tell, is basically making the .pdf
accessible to people who want to use a screen reader to 'listen' to it. I
actually use the 'read out loud' feature in Adobe to proof-read my own papers
The issues requiring attention are basically:
i) everything needs to be 'tagged' so that the screen knows whether it is
text or not.
ii) figures (plus I did tables) that cannot be read, need 'alternate text'.
Turns out this can just be 'Figure 7' etc., not a full description of
the figure (which would obviously take a thousand words...)
Tagging almost everything can be done automatically, but alternate text
has to be added manually (until we figure out how to automate it in Latex).
A Quick Check ( Advanced - Accessibility - Quick Check) on my ...Submit.pdf
file before I did any tagging, said that it had logical structure but was
not tagged, as expected. It's good to start with everything untagged I think.
3. I did the following on Adobe Acrobat 8 Professional. Repeatedly
save each iteration with a new filename in case you have to go back a stage;
you can't simply 'undo' these things.
4. Add tags - click Advanced, Accessibility, Add tags. That automatically adds
tags to the whole document.
5. Check page by page with original finalised .pdf that any figures didn't get messed up - for ours, some colours got washed out (especially green), and some filled circles became open. Manually replace those pages from the original .pdf, and manually add tags to those pages.
To Manually add tags:
Alt-T-A-G [Tools - Adv Editing - touch up reading tool] add tags to figures, caption, text and footer(=background, which I'm guessing is correct since footers don't show up as tags for other pages). Draw round the whole thing to be tagged, and choose which type of tag.
For some complicated tables you may have to re-tag, for example including any table footnotes. Some figures don't automatically include '/' and other symbols. Just re-tag around the whole thing and make a figure. Add TOC as a tag (this may be done automatically). Do title page etc. as Text, I don't think you do anything with the Fisheries and Oceans logo or the 'Canada' in the bottom-right corner of the cover page (they could not be manually tagged in one of my Res Docs ('Canada' would move to the other corner). Don't tag something as a formula - I tried this for Word equations and they all tumbled down to the bottom of the page..
Add alternate text to all figures. You can just right-click on each figure and add the alternate text - just say "Figure 5" for Figure 5, etc.. I did this, which is quicker once you get going. If you prefer just using the keyboard (especially if you have a programmable keyboard):
- View - Navigation Panels - Tags - Highlight Content
- Expand logical structure, find the first real figure. Have it highlighted. Click on options. Click on Highlight Content (shows what the Tag refers to).
- Click Options again, then
[Programmed as f5 on keyboard]:
P (for properties)
Alt-r
Figure [i.e. type "Figure " for the alternate text].
Then type in Figure number.
[Programmed as f4]:
Alt c
Down arrow (to go to next figure in Tags Panel
Keep scrolling down with arrow key to next real figure.
Click on Options.
Repeat from [Programmed as f5 on keyboard]
Some figures have multiple panels that get tagged separately - for those I usually retagged them all with the same figure name.
6. Do a Quick Check: Advanced, Accessibility, Quick Check. I think it should now pass this (basically, everything is tagged).
7. Save as filenameReport.pdf, then run Full check - make sure you tell it the right directory that you want to save the report in, and check options 1,4,6 (in Adobe 8), which are: Alt text descriptions are provided; All content is provided in the document structure; Tab order is consistent within the structure order. I had chosen these, but I think you can probably just do number 1, as the alternate text is what CSAS seems concerned with.
This pops up a summary, plus gives full details in filenameReport.pdf and ..html.
8. Basically you want to end up with 0 'images with no alternate text' and 0 'figure elements with no alternate text'.
The ..Report.pdf has comments that tell you what needs correcting. Just worry about the images/figures with no alternate text - find them in the filename.pdf document and add alt text to them (right-click figure).
In the preamble page 2 the recycle symbol was giving me grief as a figure, so I just made one big box around everything and called it text.
There already seems to be a TOC tag but it clicking on a heading/page number doesn't seem to jump to that page. Added another TOC tag (using Tag panel: View, Navigation Panels, Tags [since TOC doesn't seem to be an option with Alt-T-A-G] and highlight whole page (except footer)) to TOC and it seemed to automatically allow clicking to the correct page.
Sometimes a figure might give an error - numbers on an axis may be tagged as text instead of part of the figure - just create a new figure tag around the whole thing, which seems to replace the old tags.
Sometimes bits of an axis label may not work - e.g. / got tagged as it's own figure, so just add alt text to it or retag the whole figure.
Footnotes under tables cause problems, just re-tag the whole thing (including footnote) as a table.
It seems Word equations come out as individual figures, but if you highlight a whole page (to call it one big figure), all the equations tumble down into a pile in the bottom-right corner (!). So you have to right-click each one and add alt text. Latex equations didn't need to be fixed (except for two minor symbols that strangely got tagged as figures).
CSAS office asked me to add bookmarks. To add bookmarks, you just need to select the text and do CTRL + B, then if you have sub-titles, you will need to drag them under their main title, and that can be a bit tricky at first. Rowan said to 'fit page' for each bookmark. I can't get Adobe Acrobat 8 to show bookmark panel, and I think in the end it was automatically done in the .pdf.
FILES
*****
resDocSty.sty - this is the style file that sets some of the
formatting. I keep mine in C:\andy\latex\myStyleFiles\tex\latex\misc
(which is in my path). I haven't tidied it up as
much as I could, and it may contain a few superflous things
(e.g. the tocloft package doesn't get used).
POP3CDexample.tex - this should work. It's based on:
POP3CDresDoc.tex which was my final version, but needs figures
etc. to be in the right directories (so can't be run on other
people's computers).
mainDoc/ folder has a .tex file plus some figures, that gets called
from POP3CDexample.tex
appD-Biology/ folder is an appendix
appF-Eqns/ folder is another appendix.
This is for our Pacific Ocean Perch (2014) Research Document:
Edwards, A.M., Haigh, R. and Starr, P.J. 2014. Pacific Ocean Perch
(Sebastes alutus) stock assessment for the west coast of Vancouver
Island, British Columbia. DFO Can. Sci. Advis. Sec. Res. Doc.
2013/093: vi + 135 p.
POP3CDresDocSubmit.pdf is the final submitted version (approved
by our local CSAS office).
POP3CDresDocSubmitAccess9.pdf is the final version, with Web
Accessibility, as accepted by the CSAS office.
POP3CDresDocPreamble.doc is the preamble (first 6 pages) as
.doc so that CSAS office can edit it. Unfortunately that includes
the Table of Contents, which I did in Latex for submitting the
working paper, and then just did manually in Word (based on a
previous one we had) for the final Res Doc.
There are appendices that are kept in separate folders (like when writing
a thesis). My figures are all in the original R directories, so
I've just included a few stand alone figures and some text that should
work (though it won't correctly reference figure numbers)
abbrev4.bib - my ongoing (large!) bibliography file.
resDoc.bst - bib style file for the references. One thing I couldn't
get to work was the ordering of multi-author papers (CJFAS rules).
See CSAPbibRules.pdf.
I ended up just manually editing the .bbl file at the end, so just
don't run bibtex after that. For example, I had to do
Edwards et al. 2012b before 2013
Olsen et al. 1997 before 2008
Schnute and Richards before Schnute et al. 2001
Westrheim et al. 1968 before 1972.
In case you need it, we had a few figures that we couldn't produce
properly as postscript, but as .png or .pdf. For that we constructed
POP3CDReplace.tex, and ran
texi2dvi --pdf POP3CDReplace.tex
and replaced the relavant pages in the final .pdf.
(I run latex the old way - latex **.tex, dvips **
so I can view the postscript output in ghostview, which
automatically refreshes), and then ps2pdf **.ps to make
a final .pdf.
I had a working paper file POP3CDwp.tex, that then became
POP3CDresDoc.tex for doing revisions. To compare versions
I ran:
latexdiff --flatten POP3CDwp3.tex POP3CDresDoc.tex > POP3CDdiff.tex
which actually worked (and is the reason I use \input instead
of \subimport).
Please ask any questions. We did two companion assessments
at once, and using Sweave and Latex for a lot of the output saved
a lot of time, despite the extra work required at the end for
Web Accessibility. Plus the Sweave approach has been used in
two subsequent assessment.