Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
sep:internal:report [2009/09/30 19:19]
mohammad
sep:internal:report [2015/05/27 02:06] (current)
Line 1: Line 1:
 ====== SEP Report Guidelines ====== ====== SEP Report Guidelines ======
 +
  
 This page attempts to synthesize the current SEP report building  This page attempts to synthesize the current SEP report building 
Line 32: Line 33:
   * **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.   * **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 wikipage|sep:internal:proofread1]]. Cut and paste the following instructions: +  * **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 [[sep:internal:proofread1 | 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.
-<code> +
-pushd /net/sepwww/sepwww/pub/internal/report; co -l rev134.html; ${EDITOR} rev134.html; ci -u -z-08:00 rev134.html; popd +
-</code> +
- +
-**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. 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 (visit [[sep:internal:proofread2|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.
- +
-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.   * **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.
Line 54: Line 43:
   * **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:   * **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.pdfin each directory, you receive an email from the report builder telling you that all papers are ready for review.+**(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. **(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.
Line 82: Line 71:
   * **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 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)+  * **D minus 6 days (Fri):** Update sign-up [[sep:internal:proofread1 | signup wiki page]]:  
- +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\\ "+<code> 
 +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\\ 
 +</code>
  
-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 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.
Line 92: Line 82:
   * **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 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).+  * **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 setting for example "RESULTSNR = title.ps" and "RESDIR = ../Filler" in "Adm/Makefileand by copying "title.ps" in "Filler".+Place a title page figure (dummy or real), by copying the figure file in "Filler" and changing the ''SConstruct'' as 
 +<code> 
 +"RESULTSNR = cover.ps"  
 +"RESDIR = ../Filler"  
 +</code> 
 +Type "sconsin the "sep139" directory, then dive in the "sconsrules to see where the process crashed.
  
-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  
- +<code> 
-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".+include SEP.top 
 +RESDIR=Fig/ 
 +RESULTSER=[names of results] 
 +"same for CR and NR" 
 +include SEP.bottom 
 +</code>
  
-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.+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}".+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". 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.+Have Biondo & 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.+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) 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+Include a campus map (found in ''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. 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.
Line 121: Line 120:
   * **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.   * **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" +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".
- +
-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. 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.
sep/internal/report.1254338343.txt.gz · Last modified: 2015/05/26 22:40 (external edit)
CC Attribution-Share Alike 4.0 International
Driven by DokuWiki Recent changes RSS feed Valid CSS Valid XHTML 1.0