[BACK]Return to man.cgi.3 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/man.cgi.3, Revision 1.1

1.1     ! schwarze    1: .\"    $Id: mandoc_html.3,v 1.1 2014/07/23 18:13:09 schwarze Exp $
        !             2: .\"
        !             3: .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
        !             4: .\"
        !             5: .\" Permission to use, copy, modify, and distribute this software for any
        !             6: .\" purpose with or without fee is hereby granted, provided that the above
        !             7: .\" copyright notice and this permission notice appear in all copies.
        !             8: .\"
        !             9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
        !            10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
        !            11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
        !            12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
        !            13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
        !            14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
        !            15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
        !            16: .\"
        !            17: .Dd $Mdocdate: July 23 2014 $
        !            18: .Dt MAN.CGI 3
        !            19: .Os
        !            20: .Sh NAME
        !            21: .Nm man.cgi
        !            22: .Nd internals of the CGI program to search and display manual pages
        !            23: .Sh DESCRIPTION
        !            24: The source code of
        !            25: .Xr man.cgi 8
        !            26: is organized in four levels:
        !            27: .Pp
        !            28: .Bl -enum -compact
        !            29: .It
        !            30: .Sx Top level
        !            31: .It
        !            32: .Sx Page generators
        !            33: .It
        !            34: .Sx Result generators
        !            35: .It
        !            36: .Sx Utility routines
        !            37: .El
        !            38: .Ss Top level
        !            39: The top level of
        !            40: .Xr man.cgi 8
        !            41: consists of the
        !            42: .Fn main
        !            43: program and a few parser routines.
        !            44: .Bl -tag -width 1n
        !            45: .It Ft int Fn main void
        !            46: The main program
        !            47: .Bl -dash -compact
        !            48: .It
        !            49: limits execution time;
        !            50: .It
        !            51: changes to
        !            52: .Dv MAN_DIR ,
        !            53: the data directory containing all the manual trees;
        !            54: .It
        !            55: calls
        !            56: .Fn parse_manpath_conf ;
        !            57: .It
        !            58: calls
        !            59: .Fn parse_path_info ;
        !            60: .It
        !            61: calls
        !            62: .Fn parse_query_string
        !            63: if
        !            64: .Ev PATH_INFO
        !            65: is empty;
        !            66: .It
        !            67: validates the manpath and the architecture;
        !            68: .It
        !            69: calls the appropriate one among the
        !            70: .Sx Page generators .
        !            71: .El
        !            72: .It Ft void Fn parse_manpath_conf "struct req *req"
        !            73: Parses and validates
        !            74: .Pa manpath.conf
        !            75: and fills
        !            76: .Va req->p
        !            77: and
        !            78: .Va req->psz .
        !            79: .It Ft void Fn parse_path_info "struct req *req" "const char *path"
        !            80: Parses and validates
        !            81: .Ev PATH_INFO ,
        !            82: clears
        !            83: .Va req->isquery ,
        !            84: and fills
        !            85: .Va req->q .
        !            86: .It Ft void Fn parse_query_string "struct req *req" "const char *qs"
        !            87: Parses and validates
        !            88: .Ev QUERY_STRING ,
        !            89: sets
        !            90: .Va req->isquery ,
        !            91: and fills
        !            92: .Va req->q .
        !            93: This function is the only user of the utility functions
        !            94: .Fn http_decode
        !            95: and
        !            96: .Fn set_query_attr .
        !            97: .El
        !            98: .Ss Page generators
        !            99: The purpose of each page generator is to print a complete HTML page,
        !           100: starting with the HTTP headers and continuing to the page footer.
        !           101: Before starting HTML output with
        !           102: .Fn resp_begin_html ,
        !           103: some page generators do some preparatory work, for example to decide
        !           104: which page to show.
        !           105: Each page generator ends with a call to
        !           106: .Fn resp_end_html .
        !           107: .Bl -tag -width 1n
        !           108: .It Ft void Fn pg_show "struct req *req" "const char *fullpath"
        !           109: This page generator is used when
        !           110: .Ev PATH_INFO
        !           111: contains the complete path to a manual page including manpath,
        !           112: section directory, optional architecture subdirectory, manual name
        !           113: and section number suffix.
        !           114: It validates the manpath, changes into it, validate the filename,
        !           115: and then calls
        !           116: .Fn resp_begin_html ,
        !           117: .Fn resp_searchform ,
        !           118: .Fn resp_show ,
        !           119: and
        !           120: .Fn resp_end_html
        !           121: in that order.
        !           122: .It Ft void Fn pg_search "const struct req *req"
        !           123: This page generator is used when
        !           124: .Ev PATH_INFO
        !           125: contains a search query in short format or when
        !           126: .Ev PATH_INFO
        !           127: is empty and a
        !           128: .Ev QUERY_STRING
        !           129: is provided.
        !           130: It changes into the manpath and calls
        !           131: .Xr mansearch 3 .
        !           132: Depending on the result, it calls either
        !           133: .Fn pg_noresult
        !           134: or
        !           135: .Fn pg_searchres .
        !           136: .It Ft void Fn pg_noresult "const struct req *req" "const char *msg"
        !           137: This function calls
        !           138: .Fn resp_begin_html ,
        !           139: .Fn resp_searchform ,
        !           140: prints the
        !           141: .Fa msg
        !           142: passed to it, and calls
        !           143: .Fn resp_end_html .
        !           144: .It Ft void Fn pg_searchres "const struct req *req" "struct manpage *r"\
        !           145:  "size_t sz"
        !           146: This function first validates the filenames found.
        !           147: If
        !           148: .Ev QUERY_STRING
        !           149: was used and there is exactly one result,
        !           150: it writes an HTTP redirect to that result.
        !           151: Otherwise, it writes an HTML result page beginning with
        !           152: .Fn resp_begin_html
        !           153: and
        !           154: .Fn resp_searchform .
        !           155: If there is more than one result, it writes a list of links
        !           156: to all the results.
        !           157: If it was a
        !           158: .Xr man 1
        !           159: rather than an
        !           160: .Xr apropos 1
        !           161: query or if there is only one single result, it calls
        !           162: .Fn resp_show .
        !           163: Finally, it calls
        !           164: .Fn resp_end_html .
        !           165: .It Ft void Fn pg_index "const struct req *req"
        !           166: This page generator is used when
        !           167: .Ev PATH_INFO
        !           168: and
        !           169: .Ev QUERY_STRING
        !           170: are both empty.
        !           171: It calls
        !           172: .Fn resp_begin_html
        !           173: and
        !           174: .Fn resp_searchform ,
        !           175: writes links to help pages, and calls
        !           176: .Fn resp_end_html .
        !           177: .It Ft void Fn pg_error_badrequest "const char *msg"
        !           178: This page generator is used when
        !           179: .Fn main
        !           180: or
        !           181: .Fn pg_show
        !           182: detect an invalid URI.
        !           183: It calls
        !           184: .Fn resp_begin_html ,
        !           185: prints the
        !           186: .Fa msg
        !           187: provided, and calls
        !           188: .Fn resp_end_html .
        !           189: .It Ft void Fn pg_error_internal void
        !           190: This page generator is used by various functions when errors are
        !           191: detected in the
        !           192: .Pa manpath.conf
        !           193: configuration file, in
        !           194: .Xr mandoc.db 5
        !           195: databases, in the
        !           196: .Xr mandoc 3
        !           197: parser, in file system permissions, or when setting up timeouts.
        !           198: It calls
        !           199: .Fn resp_begin_html ,
        !           200: prints
        !           201: .Qq "Internal Server Error" ,
        !           202: and calls
        !           203: .Fn resp_end_html .
        !           204: Before calling
        !           205: .Fn pg_error_internal ,
        !           206: call
        !           207: .Xr warn 3
        !           208: or
        !           209: .Xr warnx 3
        !           210: to log the reason of the error to the
        !           211: .Xr httpd 8
        !           212: server log file.
        !           213: .El
        !           214: .Ss Result generators
        !           215: The purpose of result generators is to print a chunk of HTML code.
        !           216: When they print untrusted strings or characters,
        !           217: .Fn html_print
        !           218: and
        !           219: .Fn html_putchar
        !           220: are used.
        !           221: The highest level result generators are:
        !           222: .Bl -tag -width 1n
        !           223: .It Ft void Fn resp_begin_html "int code" "const char *msg"
        !           224: This generator calls
        !           225: .Fn resp_begin_http
        !           226: to print the HTTP headers, then prints the HTML header up to the
        !           227: opening tag of the <body> element, then copies the file
        !           228: .Pa header.html
        !           229: to the output, if it exists and is readable.
        !           230: .It Ft void Fn resp_searchform "const struct req *req"
        !           231: This generator prints a search form, filling it with data
        !           232: from the provided request object.
        !           233: .It Ft void Fn resp_show "const struct req *req" "const char *file"
        !           234: This wrapper dispatches to either
        !           235: .Fn resp_catman
        !           236: or
        !           237: .Fn resp_format ,
        !           238: depending on whether
        !           239: .Ar file
        !           240: starts with
        !           241: .Pa cat
        !           242: or
        !           243: .Pa man ,
        !           244: respectively.
        !           245: .It Ft void Fn resp_catman "const struct req *req" "const char *file"
        !           246: This generator translates a preformatted, backspace-encoded manual
        !           247: page to HTML and prints it to the output.
        !           248: .It Ft void Fn resp_format "const struct req *req" "const char *file"
        !           249: This generator formats a manual page on the standard output,
        !           250: using the functions documented in
        !           251: .Xr mchars_alloc 3
        !           252: and
        !           253: .Xr mandoc 3 .
        !           254: .It Ft void Fn resp_end_html void
        !           255: This generator copies the file
        !           256: .Pa footer.html
        !           257: to the output, if it exists and is readable,
        !           258: and closes the <body> and <html> elements.
        !           259: .El
        !           260: .Ss Utility routines
        !           261: These functions take a string and return 1 if it is valid, or 0 otherwise.
        !           262: .Bl -tag -width 1n
        !           263: .It Ft int Fn validate_urifrag "const char *frag"
        !           264: Checks that the string only contains alphanumeric ASCII characters,
        !           265: dashes, dots, slashes, and underscores.
        !           266: .It Ft int Fn validate_manpath "const struct req *req" "const char* manpath"
        !           267: Checks that the string is either
        !           268: .Qq mandoc
        !           269: or one of the manpaths configured in
        !           270: .Pa manpath.conf .
        !           271: .It Ft int Fn validate_filename "const char *file"
        !           272: Checks that the string starts with
        !           273: .Qq man
        !           274: or
        !           275: .Qq cat
        !           276: and does not ascend to parent directories.
        !           277: .El
        !           278: .Sh SEE ALSO
        !           279: .Xr mandoc 3 ,
        !           280: .Xr mansearch 3 ,
        !           281: .Xr mandoc.db 5 ,
        !           282: .Xr man.cgi 8

CVSweb