LINUX GAZETTE ARTICLES ~ means /home/lg. All programs are in ~/bin unless noted. ~/data/articles is a symlink to ~/data/issues; use whichever you prefer. ===== Preparing the issue ===== 1) Run: newissue.sh ## (## is the issue number.) This creates ~/issue##/. The program is non-destructive; you can run it even if you've already created the issue directory and put some files in it. 2) Edit ~/data/ISSUES to add a line for the next issue. 3) copy previous ~/data/issues/PREVIOUS.yml ###.yml 4) copy previous ~/data/issues/PREVIOUS.yml ###.yml 5) In ###.yml (use leading zero if necessary) delete all entries execept the ones you're sure will be in the next issue. Remember that you will have to change the titles as you receive the new articles. ===== Adding an author ===== 1) Determine the author key (AUTHOR). It's usually the last name (no spaces or special characters). If that's not unique, use "lastname.firstname" or something else. Sometimes I use the first name or nickname, especially for authors from India who do not normally advertise their last name. If you use an unusual key, tell the author to remind you of it when they submit future aricles. 2) See if ~/data/authors/AUTHOR exists and is the right person. Update the info if necessary. 3) (In the rare case that it's the wrong person, change it to "lastname.firstname" and change all author: references in ~/data/articles/*.yml .) 4) If the key doesn't exist, look in ~/data/legacyAuthors/ . If found, move it into place, update it, and make sure it's in the correct format. In particular, copy the HTML around the bio from ~/data/authors/TEMPLATE. 5) If still not found, copy ~/data/authors/TEMPLATE and modify. The file is in rfc822 (email message) format, not YAML. name: as it should be published email: as it should be published. Some authors provide a spam-obscured format. privateEmail: not published. Some authors provide a contact address for you to use. tag: 'y' if the person is a member of The Answer Gang. updated: date updated in YYYY-MM-DD format. Body is an HTML snippet that is the author's bio. Put it between and . If the author doesn't provide a bio, put HTML comment markers around it (inside the BEGN/END comments). ===== Adding an article ===== 1) Determine the author key and add the author as described above. 2) Determine the article key (ARTICLE). This is normally the same as the author key. If multiple articles by the same author, number them (ARTICLE, ARTICLE2, ARTICLE3). Other article keys I use: lg_mail : The Mailbag lg_tips : 2-Cent Tips lg_answer: The Answer Gang lg_bytes: News Bytes collinge: HelpDex cartoon strip (author collinge) ecol: Ecol cartoon strip (author malonda) qubism: Qubism cartoon strip (author harsem) foolish: The Foolish Things We Do With Our Computers (author you) lg_backpage: The Back Page (author orr) 3) Add or modify a stanza in ~/data/articles/###.yml in YAML format: --- key: okopnik author: okopnik title: Perl One-Liner of the Month key: is the article key. author: is the author key. The order of entries determines the TOC. I order articles by the article key, but leave lg_* in their fixed positions. (lg_backpage goes last if present.) 4) Put the HTML file in ~/I/ARTICLE.html (using the article key). 5) Run "refresh". This rebuilds the article database (~/data/cache.pickle) from the config files. *** ALWAYS RUN "refresh" AFTER MODIFYING ANYTHING IN ~/data/, BEFORE RUNNING ANOTHER BUILD COMMAND, or you'll get an error or the wrong result. *** 6) Run "article ARTICLE.html" (using the article key). This (re)generates the LG header/footer for the article. It can be run again later to update the header/footer if desired. 7) Clean up the article HTML, delete any style crap or fancy fonts, proofread spelling/grammar, etc. How closely you do this depends on how much time you have. You can send it to a volunteer proofreader if it has a lot of grammar mistakes. Since many LG readers speak English non-natively, we aim to be as simple as possible. Since many readers have text browsers, old browsers, Palm pilots, etc, we keep the HTML as simple as possible. Keep the number of images reasonable, since some readers pay lots of $$ for bandwidth. Look for any literal < > & which should be displayed verbatim; you'll have to change them to < > & respectively; vim highlights these in an red background so they're easy to spot. We allow authors to send text if they don't know HTML; in that case, you'll have to add the HTML tags yourself. You may want to ask some of the proofreaders to be assistant editors to lessen the load on yourself. 8) Put supplemental files in ~/I/misc/ARTICLE (using the article key) and make sure the links from the article work. Text files should usually end in .txt; e.g., program.c.txt, program2.py.txt so they show up correctly in the browser. If the article contains a long program listing the user might want to run without typing in, copy it to a text file, change < > & to < > & respectively. 9) ** ALWAYS USE RELATIVE LINKS FROM ONE PORTION OF LG TO ANOTHER. ** E.g., "misc/okopnik/flowchart.png", "../issue89/lg_bytes.html". Otherwise the links won't work when read on a mirror or off-line. Exceptions are CGI scripts, the search page, and some links to the home page; always mention that the link is to the main site. 10) When finished, save the original e-mail message in "d". ===== What we publish ===== http://www.linuxgazette.com/faq/author.html explains the guidelines for articles we publish, both re content and HTML format. ===== The Mailbag, 2-Cent Tips, The Answer Gang ===== Send the "ljwnn" mailbox to Heather Stern a week before publication. She will send you a tarball ready to publish, just untar it in ~/I. The tarball contains a file TWDT.lg_answer##.html . Move it to ~/twdt/ . It is needed for the "twdt" command below. Heather's script often puts an extra "/" in the IMG tag for the LG logo in lg_*.html. If the image is broken, check for this. Also check for any other obvious errors in the columns and let her know. ===== News Bytes ===== In the second half of the month, send Mick Conry the accumulated "bytes" mailbox. Make sure he has a weekend to work on it before the publishing date. He will send a finished column. I don't think you need to run "article" on it, but check. Copy the current LJ cover image (200x268, png) to ~I/misc/bytes/lj-cover.png and make sure it shows up all right. Copy the events from http://www.linuxjournal.com/events.php to the appropriate section in News Bytes. (Mick usually does this.) There are comment markers in the file showing where to cut. Delete any references to banner images, and any entries which will be finished by the publishing date. Guido Socher will send HTML links to Linux Focus articles (linuxfocus.org). Put these in the top of the Linux Links section or have Mick do it. Usually these come after Mick has finished News Bytes. LF is published bi-monthly. (Eventually I'd like to see the LF links on the issue TOC since it's a sister publication.) ===== Cartoons (HelpDex, Qubism, Ecol) ==== I've been assembling the cartoon articles, and I'll probably continue to do so when I'm available. Otherwise you can have the authors assemble the articles, or you can select the panels from their website or a tarball and assemble the articles yourself. To assemble the articles yourself: 1) Place the images in misc/ARTICLE/ 2) Run "cartoon ARTICLE". This creates ARTICLE.html with IMG links. The template (~/lib/python/T_Cartoon.tmpl) adds extra text for collinge (HelpDex), ecol and qubism, but you can use the command for any new cartoon series. 3) Run "article ARTICLE.html" and edit the article as usual. ===== The Foolish Things We Do With Our Computers === When you get enough messages in "foolish", assemble them into an article similar to the previous ones.