This file explains what is in pracjourn and some of how it works. updated by Dave Walden, 2/12/2005 Table of contents ############################################################### 1. Where stuff is, sort of 2. Some thing to do or at least seriously consider doing 3. File system structure 4. How to create a new issue 5. Format of the issue drive file (e.g., 2005-1.txt) 6. Format of editorial staff driver file If you see problems or have suggestions for this memo or the web site, please pass them to dave@walden-family.com The current operational version of the program is ghp-v19.pl 1. Where Stuff Is, Sort Of ############################################################### http://www.tug.org/pracjourn -- TPJ operational web site http://dw.tug.org/pracjourn -- probably where new issues or revisions to an issue are pulled together http://dw2.tug.org/pracjourn -- probably where program changes are tested http://www.walden-family.com/pracjourn -- where stuff sometimes is before it's at the TUG server 2. Some things to do or at least consider doing ############################################################### -put download icon for Adobe Acrobat on general info page -use TeX alphabet for author names in yyyy-i.txt and interpret it for various uses -comment on item, paper, column for announcements, papers, columns -perhaps change "Current Issue" on home page to something else, e.g.,

www.tug.org/pracjourn/2005-1

-add capability of subtitles to a paper, e.g., or Ask Nelly -fix individual issues URLs to not have index.html -delete index.html when creating _i.html in paper directories -it's a bit odd that in some places we use "pracjournlogo.png" and in others "/pracjourn/pracjournlogo.png", but not a problem -put _iss.tex in Common.mak in the issue directory -interpret author names using TeX alphabet when it becomes necessary -allow subtitles in TOC (what to do with them in author, title, and bibtex indexes) -allow papers or columns without authors (what do do in author and title indexes and bibtex) [there are lots of things that have been mentioned that probably only require an html template change; I haven't listed them here -- but maybe I have left off potential real program changes that should appear here] 3. File system structure ############################################################### I will not try to defend the structure described below. Considerable thought has gone into parts of it. directories ----------- 2005-1 etc. Directories with this sort of name contain the content for a specific issue, e.g., issue 1 of 2004. Within the directory is a file named 2005-1.txt which is the driver file for the table of contents for the issue. There are also subdirectories for each paper in the issue. Read below under "How to create a new issue" for a process for creating a new issue in a file such as 2005-1. authorindex This directory contains the the author index.html file. styles/latex The styles directory contains the draft style files for LaTeX in the latex directory. Presumably at some time there will also be subdirectories for other kinds of styles, e.g., styles/tex and styles/context old-stuff This directory contains files that are no longer in use but that I don't want to throw away. people This directory contains two files for each member of the editorial board: wohf-name.html and name.html. The former is just the text of the board member's bio. The latter is the fully formatted bio page for the board member. To add the bio for a new board member, put the html text for the board member in a file with the name wohf-name.html (e.g., wohf-walden.html) and update the file in pracjourn named staff-list.txt. When you next run ghp-vii.pl, the right thing will happen. [I am going to change this so the source files are in a subdirectory of people and do not have the wohf- prefix. All .html files in the subdirectory will be converted to fully formatted bio files of the same name in the directory people. sidepages This directory contains files with the text for the general information, etc., links from the home page. When ghp-vii.pl is run, pages with the same names but with headers and footers are created and stored in pracjourn. Those pracjourn pages are copyright.html, info.html, stylefiles.html and submit.html (and I won't list them again in the file section below). sponsors This directory contains logos for our sponsors. To update this, add or drop a logo file from this diretory, and go change the homepage footer in htmltemplates-ii.pl. The right thing should happen next time you run ghp-vii.pl. titleindex This directory contains the title index.html file. files ----- archive.html: the page of links to all the archived issues, itself linked to from the home page common-code.pl: the Perl subroutines used by ghp-vii.pl plus other programs I write. ghp-vii.pl: the program (version ii) which generates this web site. This program has a require statement for common-code.pl and for htmltemplates-ii.pl htmltemplplates-ii.pl: a file of html templates (version ii) for generating this web site; to update the header, footer, or format of any part of this web site, find the appropriate thing to change in this file, and then rerun ghp-vii.pl index.html: the home page logonavyongrey.jpg: what the name says pracjourn.bib: the listing of bibtex entries for all issues pracjourn.css: an html style sheet PracTeXZapfSmall.png: small version of journal logo -- currently unused readme.txt: this file staff-list.txt: driver file to create list of editorial board; see discussion of people directory above tuglogo.jpg: the same at logonavyongrey.jpg, which perhaps can be deleted 4. How to create a new issue ############################################################### My assumption is that new issues are created in the location dwalden/public_html/pracjourn The external address of this location where we will do pilot runs of new code and develop new issues is http://dw.tug.org/pracjourn/ Once an issue a new issue is ready to go, everything appropriate is copied over to www.tug.org/pracjourn To put up a new issue, an issue directory is created, e.g., /pracjourn/yyyy-i. Within this directory, directories are created for each paper, typically named with the author's last name, e.g., pracjourn/2005-1/walden. (If one author has two papers in an issue, two directories with different names should be created, e.g., walden1 and walden2.) A driver file is created with a name the same as the directory with .txt added, e.g pracjourn/yyyy-i/yyyy-i.txt, using the pattern shown in 2005-1.txt. One of the lines in the driver file is of the form issue|yyyy|i|2005-01-15| If the last field of the issue line is blank, the issue is "not published"; if the last field is the word "published", e.g., issue|yyyy|i|2005-01-15|published the issue is "published" (more about this below). [For a while it seemed a bit silly to have yyyy-i in three places (directory name, file name, and issue line in the file), but having it this way is growing on me.] The date before the "published" field is the date of publication of the issue. As long as an issue is "not published", the program does not put an index.html file in the issue directory, which should permit people working on the issue to look into paper directories in directory-and-file mode using a URL like www.tug.org/~dwalden/pracjourn/2005-1/walden When the "published" flag is set, an index.html file is created for the paper in the paper directory. When the program is not creating an index.html file for a paper, it creates a file _i.html in the paper directory. Whichever is created (_i.html or index.html), it is created according to the following procedure: A-. The file _iss.tex is written in the paper directory with issue and number information for the styles. A. A standard header is copied to the main paper file (MPF, i.e., _i.html or index.html). B. The paper title and author for the paper are copied from the yyyy-i.txt file to the MPF using formatting of the appropriate html template. C. If a file _abstract.html exists in the paper directory, the word "Abstract" with appropriate formatting is copied to the MPF. Then the content of _abstract.html is copied to the MPF. The contents of _abstract.html should be formatted in HTML exactly as it should be displayed except the word "Abstract" will not be in the file. D. If a file.pdf exists in the paper directory (where is the same as the name of the paper directory) , an appropriately formatted HTML link (.pdf name is created manually. E. If a file _links.txt exists in the paper directory, an appropriately formatted list of links to examples are created based on the content of _links.txt and copied to the MPF. The format of _links.txt is texta|filenamea textb|filenameb ... where the filename part of a line goes in the part of a link, and the text part of the line goes before the part of the link. [I am assuming that example files should all be stored with the actual paper on the TUG web site rather than as at least one paper currently does in having a URL pointing to an example on the author's own web site.] F. Next, mailto links are copied into the MPF to permit comments on the paper and ideas for new submissions. Except, if there is a line in the _links.txt file that is !!!NO STANDARD MAILTO!!! then these mailto links are left out; this is to permit some non-standard mailto links to be used via _links.txt. If a file _rev.tex exists in the paper directory, its contents is used as an ID in the subject field of the emails that result; if no such file exists, the version is "null". G. If a file _p.html exists in the paper directory, the content of that file is copied verbatim to the MPF. This is the html version of the paper. Presumably during program development, this file has another name, e.g., walden-tweaking.html; when it is time for publication, a copy with the _p.html name is created manually. H. A standard footer is copied to the MPF, and the MPF is closed. Of course, the above procedure loops over all the papers in yyyy-i.txt. Each MPF is linked to from the table of contents for the issue. The above procedure of having the program look for certain file names allows various useful combinations of content to be combined in the MPF without explicit specification of the combination that is being used at the particular time. 5. Format of the issue drive file (e.g., 2005-1.txt) ############################################################### #the issue command line should specify the same year and number as the file name; # #the way category, paper, and format command lines work should be self explanatory; # later we can change the syntax of these command lines if it is better to delimit fields in some other way; #the "file name" is actually the directory in which the paper resides; # the files are assumed to be in the folder with the name year-i where i is the issue number; # #everything on a line after a sharp sign is ignored #blank lines are ignored # \ as the last character of a line is a continuation indicator #fix: deal with no author issue, e.g., call it Editorial staff #fix: may not need trailing | any more -- may never have #formats #issue|year|number|publicationdate|published #where the last two fields are optional; the fifth #field indicates the issue status: blank (meaning the issue is still in #draft format) or "published"; the previous field gives the publication date #in the format 2005-01-15 #category|category where category is Announcements, Articles, or Columns #piece|title1|author|directory|title2|title3 where #title1 is in html display format, title2 is for sorting, #and title3 is for bibtex entries; title2 and title3 are optional; #in the other field, multiple authors are separated by " and " #some examples follow issue|2005|1|2005-01-15|published category|Announcements piece|Welcome|Lance Carnes|carnes-welcome| piece|Highlights of the PracTeX'04 conference|Lance Carnes|carnes-conference| category|Articles piece|CTAN for Starters|Jim Hefferon|hefferon| category|Columns piece|\begin{here} % getting started|Douglas Waud and Tim Null|waud|begin{here} % getting started|\ \texttt{\char`\\begin\{here\} \% getting started} piece|Travels in TeX Land: Tweaking LaTeX|David Walden|walden| piece|Ask Nelly: What is ConTeXt?; What is LaTeX3?; Why should a college student use LaTeX?; \ How do I make temporary margin notes?|The Editors|asknelly|| 6. Format of editorial staff driver file ############################################################### #order the list in the order you want the names displayed #vertical bars separate fields #field 0 = name; field 1 = filename of bio in people directory; field 2 = title; #field 3 = y or n for having written for journal #separate multiple authors with "and" #some examples follow Lance Carnes|lcarnes.html|, editor|y Kaveh Bazargan|kbazargan.html||n Jim Hefferon|jhefferon.html||y