IP Developer HOWTO for FAQ's and HOWTO's by: Michael A. Robinton, Michael@bzs.org v1.05, 3-26-99 This document describes the minimum set of information you need to get started in the Unix environment. It will briefly touch on common com- mands to move, delete and create files; as well as edit and view files. In addition, an overview of sgml-tools will be presented that allow easy creation of documents in a standard format that can be con- verted to HTML mark up language for direct viewing on the web. ______________________________________________________________________ Table of Contents 1. Introduction - Logging on to the server. 1.1 Login with Windows 95 or Windows NT 1.1.1 Logging in with 1.1.2 Logging in with 1.2 Login with Windows 3.1 or Windows for Work Groups 1.2.1 Logging in with 1.2.2 Logging in with 1.3 Login with Mac telnet or ftp 2. The Command Line environment. 2.1 Using the keyboard - Special Keystrokes 2.2 The four arrow keys 2.3 The Backspace and Delete keys 2.4 "ctrl-z" Suspend Task Key 2.5 tab key - Automatic file name completion 3. Commands, Unix -vs- Dos 3.1 cd - cd * Change directory 3.2 cp - copy * Copy files 3.3 d2u - (no/dos) * Dos to Unix file conversion 3.4 kill - (no/dos) * Kill Process 3.5 ls - dir * List Directory 3.6 less - (see more) * Paging File Reader 3.7 more - more * Paging Viewer - primitive 3.8 man - (no/dos) * Read Manual 3.9 mkdir - md or mkdir * Make directory 3.10 mv - move * Move file or directory 3.11 ps - (no/dos) * Process Status 3.12 pwd - (no/dos) * Print Working Directory 3.13 rm - del * Remove or Delete a file or directory 4. Editing with "joe" 4.1 ctrl-k h * HELP 4.2 ctrl-k b * Mark beginning of a Block 4.3 ctrl-k k * Mark the end of a blocK 4.4 ctrl-k y * Delete block 4.5 ctrl-k m * Move block 4.6 ctrl-k c * Copy block 4.7 ctrl-k u * Top of file 4.8 ctrl-k v * Bottom of file 4.9 ctrl-k l * Goto Line nnn 4.10 ctrl-k d * Save (as) do not exit 4.11 ctrl-k x * Save and eXit 4.12 ctrl-k q * Quit, do not save 4.13 Pasting from other applications 5. SGML-tools 5.1 Using sgmlcheck 5.2 WARNING about use of italics 5.3 Using sgml2html 5.4 Using sgml2txt 6. Adding IMAGES to your documents 6.1 Tags to add Images 6.2 Image tag EXAMPLES 6.2.1 Example 1: 6.2.2 Example 2: 6.2.3 Examples of internal tags: 6.3 Where to put your IMAGE files 6.4 Where to get Images 7. Viewing the HTML files 8. Copyright Notice ______________________________________________________________________ 1. Introduction - Logging on to the server. Welcome to the Unix environment on a Linux server. This document is constantly undergoing improvement. If you have information to add which will help future Ip-Developers please contact Michael@bzs.org so your contribution can be added. Before launching into the details of the nuances of Unix, let's review some of the fundamentals of logging into the server with telnet and ftp for various operating systems. The fundamental task of logging on to the server is the same for both telnet and ftp. 1.1. Login with Windows 95 or Windows NT The information below about telnet is obsolete. The home server now only accepts connection via ssh. Please see the volunteer page of the website for the links and documentation on ssh. If the telnet and/or ftp have icons on your desktop, it is easy. Just click on the icon to launch the application. 1.1.1. Logging in with telnet o click on START o type the word "telnet" o click on OK A telnet window will pop open on your screen o click Connect on the menu bar on the left side of the window. o type the host name in the host box "home.bzs.org" o click on the Connect button o at the login: prompt, type your "username" o at the password: prompt, type your "password" 1.1.2. Logging in with ftp to transfer files o click on START o type the word "ftp" o click on OK o an ftp window will pop open on your screen o at the ftp> prompt, type "open home.bzs.org" and push ENTER o click on the Connect button o at the login: prompt, type your "username" o at the password: prompt, type your "password" type "help" to get a brief list of commands. 1.2. Login with Windows 3.1 or Windows for Work Groups The login procedure for Windows 3.1 and Windows for Work Groups differs from Windows 95 and NT only in the method used to start the initial application window. 1.2.1. Logging in with telnet The information below about telnet is obsolete. The home server now only accepts connection via ssh. Please see the volunteer page of the website for the links and documentation on ssh. o activate and maximize the Program Manager Group o click File in the upper left corner of the Program Manager window o click Run... on the File menu o type the word "telnet" o click on OK o a telnet window will pop open on your screen o click Connect on the menu bar on the left side of the window. o type the host name in the host box "home.bzs.org" o click on the Connect button o at the login: prompt, type your "username" o at the password: prompt, type your "password" 1.2.2. Logging in with ftp to transfer files o activate and maximize the Program Manager Group o click File in the upper left corner of the Program Manager window o click Run... on the File menu o type the word "ftp" o click on OK o an ftp window will pop open on your screen o at the ftp> prompt, type "open home.bzs.org" and push ENTER o click on the Connect button o at the login: prompt, type your "username" o at the password: prompt, type your "password" type "help" to get a brief list of commands. 1.3. Login with Mac telnet or ftp There is an ssh compliant freeware client available for the MAC. The home server now only accepts connection via ssh. Please see the volunteer page of the website for the links and documentation on ssh. Sorry, I don't know how to use the MAC tools. I would welcome a paragraph or two from any Mac user would like to volunteer. 2. The Command Line environment. If you only use Windows or Mac, pay attention here. These applications operate ONLY in a Command Line enviroment. I will list the Unix command and it's Dos equivalent, where applicable, along with a brief explanation of the command operation. 2.1. Using the keyboard - Special Keystrokes Whenever you see a character prefaced with the letters "ctrl-", that means "hold down the ctrl key" and press the key that follows. "ctrl-z" means "hold down the ctrl key and press z 2.2. The four arrow keys on the right side of the keyboard are used to edit the com- mand line. ------ | /\ | | Up | ------ ------ ------- | Left | Down | Right | | <- | \/ | -> | ------ ------ ------- The UP and DOWN arrow keys are used to scroll through the previous commands that have been on the command line. Once a particular command is selected, the LEFT and RIGHT arrow keys scroll sideways back and forth on the command, posi- tioning the cursor where characters may be deleteded with the BACKSPACE or DELETE keys. 2.3. The Backspace and Delete keys both delete the character to the left of the cursor. In some VT100 simulations (your telnet terminal emulation), the BACKSPACE key does not function correctly. The DELETE almost always functions correctly. 2.4. "ctrl-z" Suspend Task Key At any time in most tasks, you can type ctrl-z to suspend or bail out of the task you are currently running. Once suspended, the ps and kill commands (explained later) can be used to terminate the job. The fg command can be used to re-activate the task. 2.5. tab key - Automatic file name completion The tab key used after any command will automatically complete a file or directory name if it is unique or complete the first unique letters. Hitting the tab key twice will list the directory. Example: Directory contents: Ip-Dev-1.html Ip-Dev-3.html Ip-Dev.html Ip-Dev-2.html Ip-Dev-4.html Ip-Dev.sgml type less I followed by tab, will extend the command line to: less Ip-Dev typing two tabs will list the directory. typing ".s" tab will extend the command line to: less Ip-Dev.sgml 3. Commands, Unix -vs- Dos Listed below are the Unix commands and the Dos counterparts most commonly used. Not all of the Unix commands have an equivalent Dos counterpart, since Unix is more comprehensive than Dos. 3.1. cd - cd * Change directory The Unix change directory command "cd" is identical to the one in Dos. There is a difference in syntax in that the directory is denoted with a forward slash in Unix and a back slash in Dos. Unix syntax: cd /my/first/unix/directory Dos syntax: cd \my\first\dos\directory type "cd" with no argument to return to your ~home directory type "man cd" for detailed information about this command. 3.2. cp - copy * Copy files These commands are almost identical for Unix and Dos. Syntax: cp < path/file name > or: cp -r < path/file name > or: cp < path > or: cp -r < path > -r Copy directories recursively, copying all non-directories as if they were regular files. type "man cp" for detailed information about this command. 3.3. d2u - (no/dos) * Dos to Unix file conversion The "d2u" command converts a Dos - Windows - Mac file to the Unix format. Unix files do not contain carrige return characters, only end line characters. The "d2u" command simply removes the carrige return characters. Syntax: d2u < file name > There is of course, a "u2d" command that works the same way to put the carrige returns back into the file. If you import files via the "ftp" command, they will contain the excess carrige return characters. If you simply paste the contents of the file into an edit window or generate the file on-line, they will not contain any carrige return characters. If you forget, the end of each line will look like this.``M'' 3.4. kill - (no/dos) * Kill Process The "kill" command allows you to kill or otherwise send a signal to a process running on a Unix machine. We will only touch on the abilty to kill or dispose of an unwanted task. To "kill" a task type at the command line: kill where the process id is the number assigned to the task by the operating system. See the command "ps" further on in the document. or kill -9 to "really" kill it. Some are reluctant to die. type "man kill" for detailed information about this command. 3.5. ls - dir * List Directory These commands are very similar in both Unix and Dos. ls lists the visible files in the directory ls -l (little "L") list the files in long format with their size, creation times, etc... type "man ls" for detailed information about this command. When used within an ftp window, the "ls" command may produce a long listing since the "list default" is set by the operator of the ftp site. 3.6. less - (see more) * Paging File Reader Less is a program similar to more, but which allows backward movement in the file as well as forward movement. Also, less does not have to read the entire input file before starting, so with large input files it starts up faster. Minimum command keystokes you need to know. b (N) Scroll back N lines, default is one screen. f (N) Scroll forward N lines, default is one screen. g Go to top of file. G Go to bottom of file. / string Search for string. n Find the next occurence of the search string. q Quit. type "man less" for detailed information about this command. The output of other commands may "piped" to less. ls -l | less will pipe the output of the list command to the pager to view one screen at a time. 3.7. more - more * Paging Viewer - primitive More is a filter for paging through text one screenful at a time. This version is especially primitve. Users should realize that less provides more emulation with extensive enhancements. Don't bother with more. Use less instead. type "man more" for detailed information about this command. 3.8. man - (no/dos) * Read Manual Format and display the on-line manual pages. type man for the man page on . man - uses the pager less to view the man pages. See the instructions for less (above) for manipulating the viewing screen. type "man man" for detailed information about this command. 3.9. mkdir - md or mkdir * Make directory The Unix and Dos commands are basically the same. Syntax: mkdir < dir name > type "man mkdir" for detailed information about this com- mand. 3.10. mv - move * Move file or directory The Unix and Dos commands are basically the same. Syntax: mv < from name > < to name > The mv command can be used to move files or directories. To move files from or to the "current" directory, use ./ type "man mv" for detailed information about this command. 3.11. ps - (no/dos) * Process Status ps gives a snapshot of the current processes and shows their process id's (pid's). The process id in conjunction with the kill command can be used to terminate a running process. See kill (above). type "man man" for detailed information about this command. 3.12. pwd - (no/dos) * Print Working Directory Print the name of the current working directory. Helps you find out where you are when you get lost in the directory tree. 3.13. rm - del * Remove or Delete a file or directory The rm command without options is very similar dos del with the same syntax. Used with the "-r" option, rm is similar to dos rmdir except that it will unconditionally remove all files and subdirectories if a directory is specified for > file name < . Syntax: rm < file name > or: rm -r < file/directory name > Wild card characters are allowed anywhere in the file name. type "man rm" for detailed information about this command. 4. Editing with "joe" joe is a powerful ASCII-text screen editor. It has a "mode-less" user interface which is similer to many user- friendly PC editors. Users of Micro-Pro's WordStar or Borland's "Turbo" languages will feel at home. joe can be learned and used with a "minimum" of keystrokes and the keys "page-up, page-down, right-left-up-down arrow keys" to position the cursor. Note that on some terminal emulators, page-up and page- down do not always work - sigh.... The most important keys and the minimum set to get by with are listed below. To start joe just type: joe < file name > Almost all the commands you will use in joe start with ctrl-k The most important of these is: 4.1. ctrl-k h * HELP ctrl-k h brings up the help screen. Help Screen turn off with ^KH more help with ESC . (^[.) ############################################################################# CURSOR GO TO BLOCK DELETE MISC EXIT ^B left ^F right ^U prev. screen ^KB begin ^D char. ^KJ reformat ^KX save ^P up ^N down ^V next screen ^KK end ^Y line ^T options ^C abort ^Z previous word ^A beg. of line ^KM move ^W >word ^R refresh ^KZ shell ^X next word ^E end of line ^KC copy ^O word< ^@ insert FILE SEARCH ^KU top of file ^KW file ^J >line SPELL ^KE edit ^KF find text ^KV end of file ^KY delete ^_ undo ^[N word ^KR insert ^L find next ^KL to line No. ^K/ filter ^^ redo ^[L file ^KD save ############################################################################# This screen lists almost everything you need to know to use joe. You can turn off the help screen by typing ctrl-k h a second time. 4.2. ctrl-k b * Mark beginning of a Block This key sequence marks the beginning of a block of text to delete, move, copy, search, etc.... 4.3. ctrl-k k * Mark the end of a blocK This key sequence marks the end of aa block of text to delete, move, copy, search, etc.... 4.4. ctrl-k y * Delete block This key sequence deletes a marked block of text. 4.5. ctrl-k m * Move block This key sequence moves a marked block of text to the current cursor position. 4.6. ctrl-k c * Copy block This key sequence copies a marked block of text to the current cursor postion. 4.7. ctrl-k u * Top of file This key sequence moves the cursor and viewing window to the top of file. 4.8. ctrl-k v * Bottom of file This key sequence moves the cursor and viewing window to the bottom of file. 4.9. ctrl-k l * Goto Line nnn This key sequence (ctrl-k little "L") moves the cursor to line number "nnn" where nnn is a number entered after the key sequence is pressed. You will be prompted for the number "nnn". 4.10. ctrl-k d * Save (as) do not exit This key sequence allows you to save the file with the current or new file name without exiting the editor.. 4.11. ctrl-k x * Save and eXit This key sequence saves the current file and exits joe. 4.12. ctrl-k q * Quit, do not save This key sequence quits joe. If the file has been modified, you are first prompted to see if you really want to quit without saving. 4.13. Pasting from other applications Lastly, you can use the mouse copy and paste facility of your operating system environment to paste text into the telnet window at the current cursor position. type "man joe" for detailed information about this command. 5. SGML-tools A complete guide to the sgml-tools can be found in the /home/sgml/public_html directory on this server. The README file has complete directions for accessing the example files and the documentation . The guide itself is written in SGML and both the converted HTML files and the original guide.sgml file are present in these directories for examination along with example.sgml. I suggest you copy the example.sgml file to your own directory and play with it. The SGML guide contains a complete description of the SGML markup language and examples of how it is used. Please read it and examine the example.sgml file with less or joe to learn how to use the markup. You may wish to convert the example.sgml file to HTML and view it to see how the markup tags actually work. All of the HOWTO's I have written so far, including the SGML files are located in my directory at /home/michael/public_html . Please feel free to use those files as examples. 5.1. Using sgmlcheck sgmlcheck runs an SGML parse on the specified document source. Any errors are reported to your terminal screen. No formatted version of the source is produced. Syntax: sgmlcheck < file name > type "man sgmlcheck" for detailed information about this command. 5.2. WARNING about use of italics The use of italics with the sometext tag pair must be restricted to normal body text within the document. If these tags are use in a type tag, the sgml2txt expansion will not work properly. Don't do it! 5.3. Using sgml2html sgml2html converts an SGML source file to HTML output. Output will appear in the top level file file.html and file-n.html for each section, where file is the name of the SGML source file and n is the section name. Syntax: sgml2html < file name> or: sgml2html --imagebuttons < file name > or: (same as) sgml2html -I < file name > -I or --imagebuttons Uses graphic buttons for previous and next links type "man sgml2html" for detailed information about this command. 5.4. Using sgml2txt sgml2txt converts an SGML source file to TEXT output. The SGML file is converted to a single document with table of contents, numbered section headers, etc... Syntax: sgml2txt -f -f suppresses the backspace expansion normally added when italic characters are created by this process. type "man sgml2txt" for detailed information about this com- mand. 6. Adding IMAGES to your documents One of the things lacking in sgml-tools is a way to easily add images to the resulting html files. The method described here only works when converting SGML to HTML and is incompatible with the other conversion formats such as TXT, TEX, etc... Since we only need be concerned with HTML output, this is a great work-around. 6.1. Tags to add Images Adding images involves tricking sgml-tools into ignoring the html markup tags that must be entered for the image file declaration. The sgml markup tags are a pair of label - reference tags as follows: