SEP Report Guidelines

This page attempts to synthesize the current SEP report building workflow, in response to questions that cropped up periodically and things that the report builder (myself) may forget. D denotes the day the report builder starts building the final version of the report – that's usually a Thursday, roughly 3 weeks before the first day of the sponsor meeting/SEG annual meeting. All dates are estimates with an approximation of a few days. This is not the report countdown, but only a discussion of the more ambiguous aspects of it. Diane posts the true countdown, with a link to it from the Announcements section of the main SEP page.


General SEP report workflow

  • TIME PLANNING: D minus 5 weeks, more or less. Report countdown page appears on website. Students requiring outside editing are contacted by Biondo/Diane and should allow appropriate time (1 week) for having the paper reviewed and responding to the reviewers' suggestions.
  • REFERENCES: D minus 10 days. Seminar discussion on how to enter references in LaTeX papers using SEP macros. A \cite[]{} reference will produce an output like: (Einstein, 1905). A \cite{} reference will produce an output like: Einstein (1905).

For SEP report entries do not use arbitrary reference names and do not enter them by hand in your bib file(s), but instead add \bibliography{SEP} (reads bibtex items from ${TEXMF}/bibtex/bib/sep/SEP.bib) at the end of your paper.tex, and just call the references using the following syntax (example): Einstein.sep.150.albert1 . This is: [Last name of first author].sep.[reportnumber].[paper directory name in the report]. The TEX database will fill in with the correct reference. This will also allow references to other papers in the current report.

  • PUBLICATIONS: D minus 10 days. SEP members must disclose to the sponsors the articles and conference abstracts that they published or submitted since the last report. First they must add the entries at the end of ${TEXMF}/bibtex/bib/sep/MISC.bib . This file is subject to version control mechanisms to prevent mutual overwriting by several people, so, to avoid getting your changes overwritten, please edit the file the following way (cut-and-paste these commands):
pushd ${TEXMF}/bibtex/bib/sep; co -l MISC.bib; ${EDITOR} MISC.bib; ci -u -z-08:00 MISC.bib; popd

Remember to: (1) Be brief in your editing. The file stays locked by you while it is being edited. (2) Type in a comment and end it with a single dot on a separate line as the RCS system instructs you. Otherwise the file will not be unlocked for others to use it.

If the file is already locked, do not use root privileges to unlock it (su; su - whoeverlocked; ci -u -z-08:00 MISC.bib), but instead contact the person who the RCS system says is editing the file. Otherwise, your changes will be lost when that person checks the file back in.

After you are done with MISC.bib, add a reference with the syntax \nocite{entryNameInMiscDotBib} in /net/koko/wrk1/sep[currentNumber]/Adm/pub.tex . This file should contain the publications that appeared in the last 2 years. If this file does not exist, please either ask the report builder to generate one, or adapt one from an older report.

  • BIO ENTRIES: D minus 9 days (Tue). Make additions/changes to the biographical entries and pictures in the database. To do so, on KOKO go to /usr/local/share/TEX/database and start by looking around carefully - this stuff is delicate. The files for each person MUST be named using the SEP computer system login name for that person. So if your username is albert, your picture will be named albert.ps. Do not attempt to create a pdf version of it, TeX will do it itself. The biographical entry is named [username].bio . Keep it short and look at other entries for a style model. The only fixed rule is that the entry should start with your full name in bold font, i.e.: {\bf Albert Einstein}. Then read the files README.txt and README2.txt in the directory and update the database for the new/modified biographical entry.
  • REPORT SKELETON: D minus 8 days (Wed), 9AM. You must have a report directory with at least an abstract and introduction in place for each paper you plan to have in the report. The paper must build on POMPEI when typing scons -c; scons paper.pdf.
  • FIRST DEADLINE: D minus 7 days (Thu). All but one paper must be finished. Biondo assigns experienced SEP editors for papers of people that have been told that they need extra editing help. The “sign-up for reviews” instructions below refer to the general round of reviewers in which everyone can sign up for any paper.
  • SIGN-UP FOR REVIEWS: First round: D minus 6 days (Fri). Second round: as soon as everybody signs up in Round 1. When the report builder or Diane announces for how many papers people should sign up, please edit the proofreading1 sign-up.

If the page is already locked, wait for a few moment and try later when the person who is editing the page is done. Remember to be brief in your editing. The page stays locked by you while it is being edited. You can enter your name in any available “Reviewer” fields (Reviewer 1, Reviewer 2) for any paper.

When you are announced for how many papers you are supposed to sign up in the second round of editing, use the same procedure (visit proofreading2 sign-up). The reason why we have 2 rounds is that when we had only one, the quickest people would get all the easy papers to review, and that was not fair to people who were unlucky not to be around at the first moments of the sign-up time.

  • SECOND DEADLINE: D minus 3 days (Mon), 9 AM Deadline for having papers ready for review. A “paper.pdf” must exist in each directory. Typing scons -c ; scons paper.pdf in each report directory must rebuild it. Any final decisions on whether a paper is good enough to be included in the report are made by Biondo based on this version of the paper. No more modifications to the report papers should be done until the report builder lets you know.
  • REVIEWING PAPERS: D minus 3 days (Mon) - D minus 2 days (Tue). You will print yourself the papers you will review. However, sometimes the author notices mistakes or incorporates feedback, and you do not want to review an obsolete version of the paper. To avoid this, please observe the following workflow:

(A) Some time on Monday morning, after it has been checked that: (1) everybody has signed up in all rounds of reviews, (2) that there are no papers in a condition so catastrophic that they are unfit to go into the report, and (3) there is a paper.pdf in each directory, you receive an email from the report builder telling you that all papers are ready for review.

(B) Authors who know their papers are ready email their reviewers telling they can start reviewing. Authors who have noticed small errors (typos, references, plot annotations) in their own papers that they need time to fix email their reviewers as soon as they can and let them know when the paper will be ready for review.

(C) If a reviewer does not receive an email from an author by 6 PM on Monday, then they can start reviewing the paper.

To review a paper, go to that paper's directory and print the “paper.pdf” from there. When proofreading, use the style guidelines here. Keep an eye on the reproducibility status of the figures in the paper you are reviewing. Sometimes people set all figures to NR for easy paper building, then this gets forgotten and discovered only after the report has been printed, in the reproducibility checking stage.

The deadline for returning reviewed papers in Tuesday at 6 PM, for all papers that you signed up in both rounds. However, please try to be considerate to the authors by returning the papers as soon as possible and thus giving them time to incorporate the changes you suggested.

  • FILLER PAGES D minus 1 day (Wed). If, when you are all done with your paper, the last page is odd-numbered (so in the printed version of the report it will be followed by a blank even-numbered page), you may beautify it with an image of your choice (photo, cartoon.. anything) – if you so wish. To properly create a filler page for your paper, use the following procedure:

Copy the image to /net/koko/wrk1/sep134/Filler, giving it a name that includes the name of your paper's directory (i.e. “jeff2_filler.pdf”) and link to that image from your “Fig” directory. This linking part is so that the figure will not be included in the web-downloadable version of your individual paper, which will not contain a blank end page.

  • TITLE PAGE CONTEST: D minus 1 day (Wed). Meet in the seminar room and vote for the most popular picture for the title page. This is also the last day that you can make any changes to your paper. When you are done with the paper, make sure that rm paper.pdf; scons paper.pdf in your paper directory will produce the expected output and will not crash. Use chmod -R g+r * in your paper directory to make sure the report scripts will be able to read everything.
  • REPRODUCIBILITY: D + ?.. The rules for reproducibility can be found in the preface of any SEP report (printed or one-file pdf). Make sure you do not include huge files (hundreds of megs or larger), as each directory will become a downloadable archives, and it can be difficult for faraway sponsors to download large things. Matlab reproducibility instructions can be found at Internal - Computing - Matlab

Report builder's additional workflow

  • D minus 2 weeks (Thu): Report builder checks if backups of the report directory are indeed done as they are supposed to. Makes the report directory (writable by everybody) and an Adm directory containing: (1) a Makefile adapted from a previous report and (2) a pub.tex file (holds references to articles published by SEP members) with a template.
  • D minus 10 days (Mon): Update this webpage, making sure to replace previous report numbers with new ones. Send message to SEP reminding them that the countdown has started and to check this webpage.
  • D minus 8 days (Wed): Print out first 2 pages of each paper for Biondo to read. Loop through each paper directory and use the utility psselect with the options “-p1-2” to extract the first 2 pages. See the “bb_read_abs_intro” rule in /wrk1/sep117/Adm/Makefile and similar rules in subsequent reports.
  • D minus 8 days (Wed): Now also is the time to build the preliminary table of contents, which will be needed to assign reviewers to papers. The quickest way to do it is to send to the printer a second copy of the 2-page papers built for Biondo, take the stack and write the names of the corresponding report directories on top of each front page, arrange them on a large table according to categories, edit the Makefile in the Adm directory accordingly, then type “make toc.tex” to edit the table of contents. “scons toc.pdf” or “scons paper.pdf” will likely not work because, unlike toc.tex, they need the papers to build, and if people are still working on some papers, they may not build. Use “makeTOCreadable.sh” (found in the Adm directories of SEP-128 and subsequent reports) to generate a readable TOC.

If you prefer the RCS system, you can update by

setenv rep_num 134 \\  setenv rep_adm /net/koko/wrk1/sep$rep_num/Adm\\  pushd /net/sepwww/sepwww/pub/internal/report\\  $rep_adm/makeTOCreadable.sh $rep_adm/toc.tex rev$rep_num.html -r\\  mkdir RCS\\  popd\\
  • D minus 3 days (Mon):Check that a paper.pdf exists in each directory and that all reviewer slots on the sign-up sheet are filled. Let people know that they can start reviewing and remind them the instructions on the webpage.
  • D minus 2 days (Tue): “mkdir /net/koko/wrk1/sep134/Filler”. Remind people to prepare submissions for the title page contest and filler pages.
  • D-day (Thu): Start building the report. First make a backup (Use cd /wrk1; tar -cvzf sep139.tgz sep139 to preserve file dates – breaking them can result in make rebuilds waiting to happen).

Place a title page figure (dummy or real), by copying the figure file in “Filler” and changing the SConstruct as

"RESULTSNR = cover.ps" 
"RESDIR = ../Filler" 

Type “scons” in the “sep139” directory, then dive in the “scons” rules to see where the process crashed.

If ER/CR figures start rebuilding, you may have to use drastic measures such as temporarily replacing paper report makefiles with dummy makefiles containing only

include SEP.top
RESDIR=Fig/
RESULTSER=[names of results]
"same for CR and NR"
include SEP.bottom

LaTeX problems can appear on papers written outside of the SEP computer system, for example using \input file.tex“ instead of “\sepinput{file}, if it says it does not find a file ending in .tex, this may be the cause.

It is preferred that the report is built with “LATOPTS = option=report style=amsmath”, but sometimes the “amsmath” option breaks old LaTeX keywords in papers wrote without “amsmath”. The only solution is then replacing the commands, i.e. “\matrix{}” with “\begin{matrix} \end{matrix}”.

When all is done, look at the page number that the last paper ends with, add 1 to it and insert it in the “\setcounter” line in “pub.tex”.

Have Biondo & Bob look over the table of contents and adjust it.

Use Adobe Acrobat Reader to search for question marks in “book.pdf”. These will give away unresolved figure and bibliographical references.

Sometimes the last pages (phone numbers and sponsor lists) appear double-spaced, apparently for no reason. This happens because someone, usually a person who wrote the paper from outside the SEP computer environment, used “\renewcommand\arraystretch{2.00}”, usually for double spacing a table. The solution is putting the command immediately between the “\begin{tabular}” (or taking it out altogether)

Include a campus map (found in Filler) on the last blank page in the sponsor lists, phone lists, etc

The printers will return a printed hardcopy for proofreading 1-2 business days after the pdf is uploaded to their site. Only after this is checked it can be safely stated that the report is ready.

  • Putting the report online: As soon as the single-file version is ready, place links to it from the main page and (if in spring) from Sponsor Meeting page. Make a “tar.gz” backup of the entire report directory.

Update the “HTMLDIR” variable in “Sconstruct”. Take the filler pictures out of the papers completely – the link in “Fig”, the “RESULTSNR” entry in the paper’s “Makefile” and the entry at the end of “paper.tex”.

Open “$SEPINC/Doc.rules.book” and execute the “www1” target. Do it piece by piece (first the ”.ps.gz” targets, then the “.pdf” ones, then the “html” ones), as it is highly probable to fail somewhere anyway. Inspect especially the html output, this is prone to silent failure. Missing equation gifs can appear if the “make” command is executed from another machine then “koko”. Missing figures are very frequently caused by “.eps” figures and they are solved by making a link from “filename.eps” to “filename.ps” in the “Fig” directory. Another cause of missing figures is caused by figures that want to rebuild for the html although they were fine for pdf and ps. “Sterilizing” the Makefile by copying the true one to something else and leaving only the include sepinc , RESDIR and RESULTS*R variables solves this problem.

Let the repro person know that he can start his work.

When repro is done, check for big files using the script “www_check.pl” found in “Adm”, then run “make www2” in “Adm” to make the repro archives and the html TOC.

  1. Open “/net/sepwww/private/docs/sep128/index.html” in a text editor. Replace all occurences of “../../toc_html/index.html” with “http://sepwww.stanford.edu/research/reports/new_reports.html”.
  2. As root on farne, “cd /net/sepwww/public/docs/; mkdir sep128; chown jeff.sep sep128; chmod g+w sep128”
  3. As non-root user, “cd /net/sepwww/public/docs/sep128; cp /net/sepwww/private/docs/sep128/toc_html/* .”
  4. Open “/net/sepwww/public/docs/sep128/index.html” in a text editor. Replace all occurences of “../” with “http://sepwww.stanford.edu/data/media/private/docs/sep128/
  5. The material on the TOC page may contain small equations embedded as gifs which are found in paper directories, which are in the sponsor-only area, which means that even visitors of “http://sepwww.stanford.edu/data/media/public/docs/sep128/” will be prompted for a password. The small gifs need to be identified by searching “index.html” for the string .gif, selecting those occurences of it which are part of a paper, copying them in “/net/sepwww/public/docs/sep128/”, and editing the hyperlinks accordingly.
  6. Add the report to the list at “http://sepwww.stanford.edu/research/reports/new_reports.html” and announce the publication of the report on the announcements list at “http://sepwww.stanford.edu/”.


sep/internal/report.txt · Last modified: 2015/05/27 02:06 (external edit)
CC Attribution-Share Alike 4.0 International
Driven by DokuWiki Recent changes RSS feed Valid CSS Valid XHTML 1.0