Differences

This shows you the differences between two versions of the page.

Link to this comparison view

sep:internal:report [2008/07/29 17:18]
mohammad
sep:internal:report [2015/05/27 02:06]
Line 1: Line 1:
-====== SEP Report Guidelins ====== 
  
-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 [[sep:sep_home|main SEP page]]. 
- 
-  * See also  [[sep:internal:writing| **Proofreading/Writing Report**]] 
- 
- 
-===== 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 "\bibliographystyle{sep}" and: "\bibliography{SEP}" 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 tese 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 reviewes 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 //using RCS// the sign-up file. Cut and paste the following instructions: 
- 
-"pushd /net/sepwww/sepwww/pub/internal/report; co -l rev134.html; ${EDITOR} rev134.html; ci -u -z-08:00 rev134.html; popd" 
- 
-**If the file is already locked, do not use root privileges to unlock it **("su; su - whoeverlocked; ci -u -z-08:00 rev134.html")**, 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.** 
- 
-Even if you have to unlock it using "su" from someone who has obviously forgotten to check it in, just use the "ci" command above, do not change file permissions. RCS gives the file permission 444 all the time, but you "are" able to edit it through RCS even if you are another user. 
- 
-Remember to be brief in your editing. The file stays locked by you while it is being edited. If you want to just look at the file you can do so by going to [[http://sepwww.stanford.edu/internal/report/rev123.html|http://sepwww.stanford.edu/internal/report/rev134.html]] (press reload often if people are editing it).When you are done editing, remember to type in a comment (i.e. Jeff round 1) 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. 
- 
-You can enter your name in any available "Reviewer" fields (Reviewer 1, Reviewer 2) for any paper. 
- 
-When trying to lock a file for your use a few seconds/minutes after someone else has edited and unlocked it using another machine, you may see the RCS protesting because the current date on your machine is ahead in time than the date of the paper. Type "touch rev134.html" to update the file. 
- 
-When you are announced for how many papers you are supposed to sign up in the second round of editing, use the same procedure. 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  [[sep:internal:writing|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 [[http://sepwww.stanford.edu/internal/computing/matlab.html#tip2|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 (writeable 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. 
- 
-  - **D minus 6 days (Fri):** Generate sign-up system with (an updated version of): 
- 
-" 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\\ " 
- 
-Fill in by hand 1st reviewer for inexperienced writers and eliminate 3rd reviewer slot for everyone else.Estimate the number of papers people should sign up for in the first round and let people know that they can start signing up. 
- 
-  - **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 sep134.tgz sep134" to preserve file dates – breaking them can result in make rebuilds waiting to happen). 
- 
-Place a title page figure (dummy or real), by setting for example "RESULTSNR = title.ps" and "RESDIR = ../Filler" in "Adm/Makefile" and by copying "title.ps" in "Filler". 
- 
-Type "make paper.ps" in the "Adm" directory, then dive in the "make" 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" in "Adm/Makefile", 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 John & Bob look over the table of contents and adjust it. 
- 
-Use Adobe Acrobat Reader to search for question marks in "paper.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 "sep120/Filler") on the last blank page in the sponsor lists, phone lists, etc 
- 
-When all is done, convert the ".ps" version of the report to "pdf" for printing using software for which it can be specified that no compression should be applied to images. Usually this means Adobe Distiller on a Mac or a PC. John and Bob are familiar with this operation. 
- 
-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 "Adm/Makefile" 
- 
-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. 
-  - Visually check http://sepwww.stanford.edu/private/docs/sep128/toc_html 
-  - 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". 
-  - As root on farne, "cd /net/sepwww/public/docs/; mkdir sep128; chown jeff.sep sep128; chmod g+w sep128" 
-  - As non-root user, "cd /net/sepwww/public/docs/sep128; cp /net/sepwww/private/docs/sep128/toc_html/* ." 
-  - Open "/net/sepwww/public/docs/sep128/index.html" in a text editor. Replace all occurences of "../" with "http://sepwww.stanford.edu/private/docs/sep128/" 
-  - 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/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. 
-  - 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