The "dirlist" CGI/FastCGI program system embodies a number of handy
mark-up features.  Using the links in this document, you can learn
nifty tricks to stuff in your URLs.

Note that all these features only apply to FLAT TEXT files (like
source code).  They cannot be used with HTML file, nor PDFs, nor
word docs, nor any other document which needs special rendering
(and thus cannot be massaged by "dirlist").


<b>Cookie Crumbs, Options and See Also</b>

At the top of each file is a header comprised of three sections:

 o  Cookie Crumbs : the URL to each document is broken up into clickable
                    "Hansel & Gretel" style cookie crumbs so that you
                    don't loose your way.

 o  Options       : by clicking on the [ NoMarkings | Download ] options,
                    the dirlist program will refrain from "beautifying"
                    the output and will alter the MimeType so that the
                    browser behaves differently.  The "NoMarkings" option
                    removes the line numbers, but the document should
                    still render inside the browser.  The "Download" option
                    sets the MimeType to "application/download" which
                    will normally force the browser to give you the "Save As"
                    dialog.

 o SeeAlso        : a conditionally and dynamically generated set of URLs
                    is displayed by applying pattern matching to the existing
                    URL and "stat'ing" the corresponding patterns.  This
                    feature is controlled entirely by the "SeeAlso" variables
                    in <a href=/dir/.dirlist.ini>.dirlist.ini</a>.

<b>Zooming to a Line Number with: #NNN</b>

Each line of marked-up text, has a special anchor &lt;a name=NNNNN&gt; which
allows you to tell the browser which line number you want to "zoom" to.
The examples below will "zoom to" different line numbers of some latin text:

     Try this: <a target=new href=latin.txt#200>#200</a> <a target=new href=latin.txt#500>#500</a> <a target=new href=latin.txt#2000>#2000</a>



<b>Picking out a Section with: show=NNN[-NNN]</b>

Occasionally, a file is so large that instead of waiting for the whole
thing to render in the browser, you want to pick out a single section
of the document.  This can be accomplished by using show=NNN.

     Try this: <a target=new href=latin.txt?show=1768-1790>show=1768-1790</a>

Note that absolute line numbers are retained according to the original
document (as are the line number anchors).



<b>Grepping for Strings with: grep=xxx</b>

To "grep" for all occurances of a word and highlight it in the output,
you use the "grep=xxx" in the query string.  Note that regular
expressions are not supported, but all "grep strings" are insensative
to case (fubar and FuBar are treated the same).

     Try this: <a target=new href=latin.txt?grep=hic>grep=hic</a>

When one highlights a word (with grep=), it's usually customary to
"automatically zoom" to the first occurrance.  You can accomplish this
by adding "#g1".  The server places an anchor &lt;a name=gNNN&gt; on each
line that contains the grep string.  The browser does the rest of the
work by zooming to the first anchor.

     Try this: <a target=new href=latin.txt?grep=hic#g1>grep=hic#g1</a>

If the document does not contain any matching strings, the browser
happily ignores the erroneous anchor:

     Try this: <a target=new href=latin.txt?grep=bogus#g1>grep=bogus#g1</a>

If you know there are at least "N" occurrances of a particular grep string,
you can of course zoom to the Nth occurrance using this same technique:

     Try this: <a target=new href=latin.txt?grep=vita#g10>grep=vita#g10</a> <a target=new href=latin.txt?grep=est#g150>grep=est#g150</a>



<b>Highlighting Certain Rows with: mark=NNN[-NNN]</b>

Occasionally, you will want to highlight an entire row of a document (or
piece of source code), rather than a grep string.

     Try this: <a target=new href=latin.txt?mark=7>mark=7</a>

Other times, you will want to highlight a section of a document.

     Try this: <a target=new href=latin.txt?mark=23-25>mark=23-25</a>

Note that this feature is oriented around line-numbers.  It does not
understand anything about the text it is highlighting.



<b>Combining Features</b>

There is no reason why all these features cannot be combined.

     Try this: <a target=new href=latin.txt?show=100-500&grep=spirit&mark=137-141#127>show=100-500&grep=spirit&mark=137-141#127</a>



<b>The tags=ok Feature</b>

Normally all HTML mark-up in a page is "escaped" so that tags are
not rendered by the browser, but rather show up as code.  Normally,
a browser would render the following statement as a LINK, but the
"dirlist" program automatically escapes all left brackets &lt; so
that the browser does not see the tags:

    &lt;a href="http://www.yahoo.com"&gt;the link text&lt;/a&gt;

Occasionally, however, you actually want to see the tags rendered
instead of seeing them as code.  If you add "tags=ok" to the URL,
then "dirlist" will skip its normal escape logic.  Incidentally,
this is how *this* page should be rendered (otherwise all the
hyper links will show up as code).

If you name your source file with the extension ".tags" (like this
one) you get this feature by default.