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

Diff for /mandoc/mandoc_html.3 between version 1.1 and 1.16

version 1.1, 2014/07/23 18:13:09 version 1.16, 2018/06/25 14:13:54
Line 1 
Line 1 
 .\"     $Id$  .\"     $Id$
 .\"  .\"
 .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>  .\" Copyright (c) 2014, 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
 .\"  .\"
 .\" Permission to use, copy, modify, and distribute this software for any  .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above  .\" purpose with or without fee is hereby granted, provided that the above
Line 25 
Line 25 
 .Ft void  .Ft void
 .Fn print_gen_decls "struct html *h"  .Fn print_gen_decls "struct html *h"
 .Ft void  .Ft void
   .Fn print_gen_comment "struct html *h" "struct roff_node *n"
   .Ft void
 .Fn print_gen_head "struct html *h"  .Fn print_gen_head "struct html *h"
 .Ft struct tag *  .Ft struct tag *
 .Fo print_otag  .Fo print_otag
 .Fa "struct html *h"  .Fa "struct html *h"
 .Fa "enum htmltag tag"  .Fa "enum htmltag tag"
 .Fa "int sz"  .Fa "const char *fmt"
 .Fa "const struct htmlpair *p"  .Fa ...
 .Fc  .Fc
 .Ft void  .Ft void
 .Fo print_tagq  .Fo print_tagq
Line 48 
Line 50 
 .Fa "struct html *h"  .Fa "struct html *h"
 .Fa "const char *word"  .Fa "const char *word"
 .Fc  .Fc
   .Ft char *
   .Fo html_make_id
   .Fa "const struct roff_node *n"
   .Fc
   .Ft int
   .Fo html_strlen
   .Fa "const char *cp"
   .Fc
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The mandoc HTML formatter is not a formal library.  The mandoc HTML formatter is not a formal library.
 However, as it is compiled into more than one program, in particular  However, as it is compiled into more than one program, in particular
Line 84  These structures are declared in
Line 94  These structures are declared in
 .Bl -tag -width Ds  .Bl -tag -width Ds
 .It Vt struct html  .It Vt struct html
 Internal state of the HTML formatter.  Internal state of the HTML formatter.
 .It Vt struct htmlpair  
 Holds one HTML attribute.  
 Members are  
 .Fa "enum htmlattr key"  
 and  
 .Fa "const char *val" .  
 Helper macros  
 .Fn PAIR_*  
 are provided to support initialization of such structures.  
 .It Vt struct tag  .It Vt struct tag
 One entry for the LIFO stack of HTML elements.  One entry for the LIFO stack of HTML elements.
 Members are  Members are
Line 110  and
Line 111  and
 declarations required for the current document type.  declarations required for the current document type.
 .Pp  .Pp
 The function  The function
   .Fn print_gen_comment
   prints the leading comments, usually containing a Copyright notice
   and license, as an HTML comment.
   It is intended to be called right after opening the
   .Aq Ic HTML
   element.
   Pass the first
   .Dv ROFFT_COMMENT
   node in
   .Fa n .
   .Pp
   The function
 .Fn print_gen_head  .Fn print_gen_head
 prints the opening  prints the opening
 .Aq Ic META  .Aq Ic META
Line 134  The function
Line 147  The function
 .Fn print_otag  .Fn print_otag
 prints the start tag of an HTML element with the name  prints the start tag of an HTML element with the name
 .Fa tag ,  .Fa tag ,
 including the  optionally including the attributes specified by
 .Fa sz  .Fa fmt .
 attributes that can optionally be provided in the  If
 .Fa p  .Fa fmt
 array.  is the empty string, no attributes are written.
 It uses the private function  Each letter of
 .Fn print_attr  .Fa fmt
 which in turn uses the private function  specifies one attribute to write.
   Most attributes require one
   .Va char *
   argument which becomes the value of the attribute.
   The arguments have to be given in the same order as the attribute letters.
   If an argument is
   .Dv NULL ,
   the respective attribute is not written.
   .Bl -tag -width 1n -offset indent
   .It Cm c
   Print a
   .Cm class
   attribute.
   This attribute letter can optionally be followed by the modifier letter
   .Cm T .
   In that case, a
   .Cm title
   attribute with the same value is also printed.
   .It Cm h
   Print a
   .Cm href
   attribute.
   This attribute letter can optionally be followed by a modifier letter.
   If followed by
   .Cm R ,
   it formats the link as a local one by prefixing a
   .Sq #
   character.
   If followed by
   .Cm I ,
   it interpretes the argument as a header file name
   and generates a link using the
   .Xr mandoc 1
   .Fl O Cm includes
   option.
   If followed by
   .Cm M ,
   it takes two arguments instead of one, a manual page name and
   section, and formats them as a link to a manual page using the
   .Xr mandoc 1
   .Fl O Cm man
   option.
   .It Cm i
   Print an
   .Cm id
   attribute.
   .It Cm \&?
   Print an arbitrary attribute.
   This format letter requires two
   .Vt char *
   arguments, the attribute name and the value.
   The name must not be
   .Dv NULL .
   .It Cm s
   Print a
   .Cm style
   attribute.
   If present, it must be the last format letter.
   In contrast to the other format letters, this one does not yet
   print the value and does not take an argument.
   Instead, the rest of the format string consists of pairs of
   argument type letters and style name letters.
   .El
   .Pp
   Argument type letters each require one argument as follows:
   .Bl -tag -width 1n -offset indent
   .It Cm s
   Requires one
   .Vt char *
   argument, used as a style value.
   .It Cm u
   Requires one
   .Vt struct roffsu *
   argument, used as a length.
   .El
   .Pp
   Style name letters decide what to do with the preceding argument:
   .Bl -tag -width 1n -offset indent
   .It Cm \&?
   The special pair
   .Cm s?
   requires two
   .Vt char *
   arguments.
   The first is the style name, the second its value.
   The style name must not be
   .Dv NULL .
   .El
   .Pp
   .Fn print_otag
   uses the private function
 .Fn print_encode  .Fn print_encode
 to take care of HTML encoding.  to take care of HTML encoding.
 If required by the element type, it remembers in  If required by the element type, it remembers in
Line 174  and
Line 277  and
 .Fn print_tagq  .Fn print_tagq
 functions.  functions.
 .Pp  .Pp
 The functions  The function
 .Fn bufinit ,  .Fn html_make_id
 .Fn bufcat* ,  takes a node containing one or more text children
 and  and returns a newly allocated string containing the concatenation
 .Fn buffmt*  of the child strings, with blanks replaced by underscores.
 do not directly produce output but buffer text in the  If the node
 .Fa buf  .Fa n
 member of  contains any non-text child node,
 .Fa h .  .Fn html_make_id
 They are not used internally by  returns
 .Pa html.c  .Dv NULL
 but intended for use by the language-specific formatters  instead.
 to ease preparation of strings for the  The caller is responsible for freeing the returned string.
 .Fa p  
 argument of  
 .Fn print_otag  
 and for the  
 .Fa word  
 argument of  
 .Fn print_text .  
 Consequently, these functions do not do any HTML encoding.  
 .Pp  .Pp
   The function
   .Fn html_strlen
   counts the number of characters in
   .Fa cp .
   It is used as a crude estimate of the width needed to display a string.
   .Pp
 The functions  The functions
 .Fn html_strlen ,  
 .Fn print_eqn ,  .Fn print_eqn ,
 .Fn print_tbl ,  .Fn print_tbl ,
 and  and
Line 245  implementation of common mandoc utility functions
Line 345  implementation of common mandoc utility functions
 .An -nosplit  .An -nosplit
 The mandoc HTML formatter was written by  The mandoc HTML formatter was written by
 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .  .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
 This manual was written by  It is maintained by
 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .  .An Ingo Schwarze Aq Mt schwarze@openbsd.org ,
   who also wrote this manual.
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.16
CVSweb