ITauthor

A little reminder (because I hadn't done it for a while and had to look it up) of how to tar and zip and unzip and untar files. First up, a recap on tarring and zipping. Tarring pulls a directory full of files and subdirectories together into a single file. Zipping a file compresses it. > To tar a directory use the command: tar cvf destinationfile.tar directory This creates a file called destinationfile.tar containing the entire contents of the directory called directory (including any subdirectories). The c flag means create (rather than append to an existing file). The v flag means use verbose mode (i.e. print a notification of each file that is tarred). The f flag means you're going to specify the name of the tar file rather than using the value of the TAPE environment variable or the default value defined in /etc/default/tar. The verbose details get printed to standard error, which is the screen by default. You can redirect standard error to a file if you want to capture the output. This is a good idea if you are tarring a lot of files, otherwise the details of any problems appear briefly on the screen before being replaced by more information. If you capture the verbose details you can check what happened when the process completes. To capture the verbose details for the previous example: In the C shell: (tar cvf destinationfile.tar directory) >& log.txt In bash: (tar cvf destinationfile.tar directory) 2> log.txt > Once you've got your tar file, nine times out of ten you're going to want to zip it. To zip the tar file, use gzip: gzip destinationfile.tar This replaces destinationfile.tar with a compressed file called destinationfile.tar.gz. If you want to keep the original tar file, take a copy of it before zipping it. > To unzip a file zipped with gzip, use gunzip: gunzip destinationfile.tar.gz As you'd expect, this replaces destinationfile.tar.gz with a decompressed file called destinationfile.tar. > To untar your tar file: tar xvf destinationfile.tar This unpacks the tar file, recreating the original tarred directory as a subdirectory of the current directory. If a directory of the same name already exists the files from the tar file are added to it, overwriting any files of the same name. Existing files with different names are not removed. The tar file is not deleted. > If you want to see what's in a tar file, without going to the lengths of untarring it, use the command: tar tvf tarfile.tar The t flag lists the table of contents for the file. If you want to check whether the tar file contains a file called myfile.fm, you can use the command: tar tf tarfile.tar *myfile.fm If you want to check for files called alsfile.txt, alistairsfile.fm, bobsfile.doc, etc. you could use the command: tar tvf tmp.tar | grep .*sfile\.... The \. is the dot character. The final three dots is the regexp way of saying any three characters. Using this method, you can untar selected files. For example, to untar just files whose names end .fm use the command: tar xvf tarfile.tar `tar tf tarfile.tar | grep \.fm$` In this command the dollar sign is the regexp way of denoting the end of a line. This command would unpack all the .fm files, recreating the directory structure in which they originally lived. If you are untarring a single file and you don't want to recreate all the directories that originally housed it, but you just want the file to be unpacked into the current directory, you can use the following syntax: tar xvfO tarfile.tar *myfile.txt > myfile.txt The O flag (that's a capital "oh") isn't documented in the man page, but I just tried it and it had the desired effect. It sends the output of the process to standard output, which allows you to redirect it to a file. However, beware! If you use a command such as: tar xvfO tarfile.tar `tar tf tarfile.tar | grep .*file\.txt$` > myfile.txt you are asking for trouble, because more than one file may be matched by grep and unpacked by tar, and the contents of all of the unpacked files will end up in the specified output file (myfile.txt in this case).

Because of the annoyingly different way that IE and Mozilla handle margins and padding, I needed to modify a style for an h2 heading in IE only – adding a little padding at the top to move the heading down slightly in IE. In Mozilla it looked OK, so I wanted to detect the browser and if it was IE, change the stylesheet. The page was a one-off, so I didn't want to go down the route of having 2 external stylesheet files, I wanted to keep everything in the page itself. The solution I used owes something to the information on www.quirksmode.org/dom/changess.html, which explains how to reference a rule within a stylesheet from a JavaScript statement. So, I have a stylesheet beginning: and then, after the stylesheet, the following JavaScript: This has no effect in browsers other than IE. In IE the first rule in the first stylesheet on the page (styleSheets[0].rules[0]) gets modified, changing the marginTop style to 18 pixels.

While searching for some information about browser detection I came across Peter-Paul Koch's web site: www.quirksmode.org. Peter-Paul is a freelance web developer whose web site is full of useful information about web technology.

I've uploaded my old 2002 Radio weblog Thoughts from a technical author onto this site. The pages had been sitting, undeleted on a Userland server since my try-out of Radio expired in August 2002. Thoughts from a technical author was my first experiment in blogging and, like so many weblogs, it doesn't exactly make riveting reading. But, if I haven't put you off, you can step back in time to 19 July 2002 when I posted my first entry.

My regular newsletter from Cherryleaf pointed me in the direction of a helpful article by Pat Holt, a former book review editor and critic for the San Francisco Chronicle. In Ten Mistakes Writers Don't See (but can easily fix when they do), she alerts us to habitual errors that are all too easy to slip into. Ms Holt is talking about creative writing, but most of the points she makes apply just as well to technical writing. Number 1 on her list is Repeats. As a technical author I am very aware of repeating myself time and time and time again. So often there's just no way around it, but I really should try harder to stop using "crutch" words. My favourite of these is "typically", which I use all the time because I'm describing software that is extremely configurable. Almost every part of the system can be configured to look and behave differently, according to customers' requirements. So I never know how something will look or respond and I end up starting sentences, "Typically, ...". Number 3 on the list is another good one: Empty Adverbs. Actually, I'm really not terribly prone to this problem. However, all technical authors should recite Pat Holt's mantra: "Precise and spare; precise and spare; precise and spare." For online help in particular, this surely describes the style we should always be trying to achieve. Most technical authors should probably have number 9 (Awkward Phrasing) tatooed on the back of their hands: Awkward phrasing makes the reader stop in the midst of reading and ponder the meaning of a word or phrase. This you never want as an author. A rule of thumb - always give your work a little percolatin' time before you come back to it. Never write right up to deadline. Return to it with fresh eyes. You'll spot those overworked tangles of prose and know exactly how to fix them. Pat Holt's site (www.holtuncensored.com) is worth a visit. For one thing it's very nicely designed by www.hyperarts.com.