HELP primer

QUESTIONS

  • 1. Is there any documentation for SDSS software?
  • 2. What is a "doc" directory?
  • 3. What are all the different kinds of files in these directories?
  • 4. How can I view .txt files?
  • 5. How can I view .tex or .dvi files?
  • 6. How can I view .ps files?
  • 7. How can I view .man files?
  • 8. How can I view .html files?
  • 9. How can I write a .html file?
  • 10. How can I look at what I have done to see if it looks good?
  • 11. What else should I read to learn how to write these files?
  • 12. What are good documents to read?
  • 13. What about command line help from dervish?
  • 14. Can I define command line help in TCL?
  • ANSWERS

    1. Is there any documentation for SDSS software? Yes, there is plenty. Once you learn a few things about where to look for help files, how to read them, and what is available, then you will find the answers to many of your questions. Much of the documentation was written by people on SDSS. Some has been written by people at FNAL for other projects, and the rest is from people who are not even on the SDSS. We try to make the documentation uniformly available. 2. What is a "doc" directory? Every product that is set up should have at least one subdirectory that contains documents. For example: % setup dervish % cd $DERVISH_DIR % cd doc 3. What are all the different kinds of files in these directories? We try to use the same appendix for the same kind of file. Here are some common types: .txt a plain text file that you can read and print .tex a TeX or LaTeX file that should be processed .dvi an intermediate stage; usually between .tex and .ps .ps postscript; either a document or a picture .man these are formatted to be manual pages. Sometimes they are in a subdirectory called man/ or manual/, and sometimes they are here. Often they are accompanied by a .txt file. .html a text file with special directives that are interpreted by hypertext reading programs. html seems to stand for "Hyper Text Markup Language". 4. How can I view .txt files? These are the easiest. Print them on a normal text printer, or read them on screen with a text editor, or UNIX commands such as more. 5. How can I view .tex or .dvi files? You can read the .tex file directly, or look at the document it produces. The program xdvi is a way to preview the formatted output on the screen before printing. 6. How can I view .ps files? Print them on a postscript printer. Use a program such as ghostview to preview them. 7. How can I view .man files? If the MANPATH is set up correctly for you, then the man command will work. For example: % setup tcl % man tcl Displays the manual pages for tcl. % man tcl > temp.txt produces a temporary text file which can be printed. If you know the name of a specific file, % nroff -man $TCL_DIR/doc/TildeSubst.man | more shows the help for TildeSubst. The text file tildesubst.txt contains the same information, as plain text. 8. How can I view .html files? This is a "hypertext" language. One way to look at them is to use the xmosaic program from NCSA: % setup www % setup dss % setenv DISPLAY hostname:0.0 (where hostname is the name of your host) % xmosaic & This starts up an xwindow. The top menu page of this service has pointers into the rest of the information: phot, dervish, ftcl, www, astro, and STScI. Click on one of those words to read more. Help for the xmosaic program itself is available in the Help selection at the top. 9. How can I write a .html file? One introduction to writing .html is the document called "HTML Reference Guide" located in $INT_DIR as evenpage.ps and odd_page.ps. This is example.html Simple example of an HTML document.

    A simple example.

    This is a simple HTML document. This is the first paragraph.

    This is the second paragraph. This is a word in italics. This is a word in bold. Here is an inlined xbm image: .

    This is the third paragraph. Here is a hypertext link from the word foo to a document called "foo.html".

    A second-level header.

    Here is a section of text that should show up in a fixed-width font (as if it were a computer listing or a verse of poetry):

        The cat in the hat
        fell to the ground and went splat.
    
    This is a bulleted list with two items:

    This is the end of my example document.

    Chris Stoughton
    10. How can I look at what I have done to see if it looks good? To view this file with xmosaic, use the command: % xmosaic $INT_DIR/help/example.html & 11. What else should I read to learn how to write these files? While you are using Xmosaic, you can take a look at the .html file that creates the display. This is the quickest way to answer the question, "How did they do that?" On the menu bar, hold the left button down on File, and drag down to Document Source. This will open another window that shows you the plain text source, with all the html markings, that creates the page you are looking at. Since there are only a few html commands to learn, you can learn most of what you need to know by looking at a few of these examples. Note that when we use links to other files, make the pathname relative to the home page ( use ../../whatever) rather than an absolute pathname. This makes the html files work when they move to different disks or machines. 12. What are good documents to read? The style guide, FNAL PN473 can be found in: % setup www_server % cd $WWW_SERVER_DIR/doc The file is called pn473.ps. A couple of templates, for authors, a "home" page, and an index, are in: % setup unix_tools % cd $GENERIC_TOOLS_DIR/template There is also a reference written by Pete Deuel. See the file ref_README and the postscript files evenpage.ps and odd_page.ps in $INT_DIR/help. 13. What about command line help from dervish? You can access help for most dervish, pgPlot, and TCL commands directly from the dervish command line using the help command: dervish> help pgBegin pgBegin USAGE: pgBegin [device [xsub ysub]] Begin PGPLOT, open the plot file dervish> help expr expr expr arg Calls the expression processor to evaluate arg, and returns the result as a string. See the section EXPRESSIONS in tcl Man Pages for a detailed description dervish> help -search=expr -full (Will search for and print any help text that contains "expr".) 14. Can I define command line help in TCL? Yes, use the ftclHelpDefine command. In dervish, you enter: dervish> ftclHelpDefine facility command helpText Where facility is the general class of command you are entering. Command is the TCL command or procedure that you wish to define help for. helpText is the help string. You can embed newlines "\n" in it. The user can access it via the help text. For example: dervish> ftclHelpDefine myPipeLine myCommand "Help for my command" dervish> help myCommand myCommand Help for my command