[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.16 and 1.23

version 1.16, 2018/06/25 14:13:54 version 1.23, 2020/04/24 13:13:06
Line 21 
Line 21 
 .Nm mandoc_html  .Nm mandoc_html
 .Nd internals of the mandoc HTML formatter  .Nd internals of the mandoc HTML formatter
 .Sh SYNOPSIS  .Sh SYNOPSIS
 .In "html.h"  .In sys/types.h
   .Fd #include """mandoc.h"""
   .Fd #include """roff.h"""
   .Fd #include """out.h"""
   .Fd #include """html.h"""
 .Ft void  .Ft void
 .Fn print_gen_decls "struct html *h"  .Fn print_gen_decls "struct html *h"
 .Ft void  .Ft void
Line 46 
Line 50 
 .Fa "const struct tag *suntil"  .Fa "const struct tag *suntil"
 .Fc  .Fc
 .Ft void  .Ft void
   .Fn html_close_paragraph "struct html *h"
   .Ft enum roff_tok
   .Fo html_fillmode
   .Fa "struct html *h"
   .Fa "enum roff_tok tok"
   .Fc
   .Ft int
   .Fo html_setfont
   .Fa "struct html *h"
   .Fa "enum mandoc_esc font"
   .Fc
   .Ft void
 .Fo print_text  .Fo print_text
 .Fa "struct html *h"  .Fa "struct html *h"
 .Fa "const char *word"  .Fa "const char *word"
 .Fc  .Fc
   .Ft void
   .Fo print_tagged_text
   .Fa "struct html *h"
   .Fa "const char *word"
   .Fa "struct roff_node *n"
   .Fc
 .Ft char *  .Ft char *
 .Fo html_make_id  .Fo html_make_id
 .Fa "const struct roff_node *n"  .Fa "const struct roff_node *n"
   .Fa "int unique"
 .Fc  .Fc
 .Ft int  .Ft struct tag *
 .Fo html_strlen  .Fo print_otag_id
 .Fa "const char *cp"  .Fa "struct html *h"
   .Fa "enum htmltag tag"
   .Fa "const char *cattr"
   .Fa "struct roff_node *n"
 .Fc  .Fc
   .Ft void
   .Fn print_endline "struct html *h"
 .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 96  These structures are declared in
Line 124  These structures are declared in
 Internal state of the HTML formatter.  Internal state of the HTML formatter.
 .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 include
 .Fa "enum htmltag tag"  .Fa "enum htmltag tag"
 and  and
 .Fa "struct tag *next" .  .Fa "struct tag *next" .
Line 105  and
Line 133  and
 The function  The function
 .Fn print_gen_decls  .Fn print_gen_decls
 prints the opening  prints the opening
 .Ao Pf \&? Ic xml ? Ac  
 and  
 .Aq Pf \&! Ic DOCTYPE  .Aq Pf \&! Ic DOCTYPE
 declarations required for the current document type.  declaration.
 .Pp  .Pp
 The function  The function
 .Fn print_gen_comment  .Fn print_gen_comment
Line 167  the respective attribute is not written.
Line 193  the respective attribute is not written.
 Print a  Print a
 .Cm class  .Cm class
 attribute.  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  .It Cm h
 Print a  Print a
 .Cm href  .Cm href
Line 212  Print a
Line 233  Print a
 .Cm style  .Cm style
 attribute.  attribute.
 If present, it must be the last format letter.  If present, it must be the last format letter.
 In contrast to the other format letters, this one does not yet  It requires two
 print the value and does not take an argument.  .Va char *
 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.  arguments.
 The first is the style name, the second its value.  The first is the name of the style property, the second its value.
 The style name must not be  The name must not be
 .Dv NULL .  .Dv NULL .
   The
   .Cm s
   .Ar fmt
   letter can be repeated, each repetition requiring an additional pair of
   .Va char *
   arguments.
 .El  .El
 .Pp  .Pp
 .Fn print_otag  .Fn print_otag
Line 257  is used to close out all open elements up to and inclu
Line 261  is used to close out all open elements up to and inclu
 .Fn print_stagq  .Fn print_stagq
 is a variant to close out all open elements up to but excluding  is a variant to close out all open elements up to but excluding
 .Fa suntil .  .Fa suntil .
   The function
   .Fn html_close_paragraph
   closes all open elements that establish phrasing context,
   thus returning to the innermost flow context.
 .Pp  .Pp
 The function  The function
   .Fn html_fillmode
   switches to fill mode if
   .Fa want
   is
   .Dv ROFF_fi
   or to no-fill mode if
   .Fa want
   is
   .Dv ROFF_nf .
   Switching from fill mode to no-fill mode closes the current paragraph
   and opens a
   .Aq Ic PRE
   element.
   Switching in the opposite direction closes the
   .Aq Ic PRE
   element, but does not open a new paragraph.
   If
   .Fa want
   matches the mode that is already active, no elements are closed nor opened.
   If
   .Fa want
   is
   .Dv TOKEN_NONE ,
   the mode remains as it is.
   .Pp
   The function
   .Fn html_setfont
   selects the
   .Fa font ,
   which can be
   .Dv ESCAPE_FONTROMAN ,
   .Dv ESCAPE_FONTBOLD ,
   .Dv ESCAPE_FONTITALIC ,
   .Dv ESCAPE_FONTBI ,
   or
   .Dv ESCAPE_FONTCW ,
   for future text output and internally remembers
   the font that was active before the change.
   If the
   .Fa font
   argument is
   .Dv ESCAPE_FONTPREV ,
   the current and the previous font are exchanged.
   This function only changes the internal state of the
   .Fa h
   object; no HTML elements are written yet.
   Subsequent text output will write font elements when needed.
   .Pp
   The function
 .Fn print_text  .Fn print_text
 prints HTML element content.  prints HTML element content.
 It uses the private function  It uses the private function
Line 278  and
Line 335  and
 functions.  functions.
 .Pp  .Pp
 The function  The function
 .Fn html_make_id  .Fn print_tagged_text
 takes a node containing one or more text children  is a variant of
 and returns a newly allocated string containing the concatenation  .Fn print_text
 of the child strings, with blanks replaced by underscores.  that wraps
 If the node  .Fa word
   in an
   .Aq Ic A
   element of class
   .Qq permalink
   if
 .Fa n  .Fa n
 contains any non-text child node,  is not
   .Dv NULL
   and yields a segment identifier when passed to
   .Fn html_make_id .
   .Pp
   The function
 .Fn html_make_id  .Fn html_make_id
 returns  allocates a string to be used for the
   .Cm id
   attribute of an HTML element and/or as a segment identifier for a URI in an
   .Aq Ic A
   element.
   If
   .Fa n
   contains a
   .Fa tag
   attribute, it is used; otherwise, child nodes are used.
   If
   .Fa n
   is an
   .Ic \&Sh ,
   .Ic \&Ss ,
   .Ic \&Sx ,
   .Ic SH ,
   or
   .Ic SS
   node, the resulting string is the concatenation of the child strings;
   for other node types, only the first child is used.
   Bytes not permitted in URI-fragment strings are replaced by underscores.
   If any of the children to be used is not a text node,
   no string is generated and
 .Dv NULL  .Dv NULL
 instead.  is returned instead.
 The caller is responsible for freeing the returned string.  If the
   .Fa unique
   argument is non-zero, deduplication is performed by appending an
   underscore and a decimal integer, if necessary.
   If the
   .Fa unique
   argument is 1, this is assumed to be the first call for this tag
   at this location, typically for use by
   .Dv NODE_ID ,
   so the integer is incremented before use.
   If the
   .Fa unique
   argument is 2, this is ssumed to be the second call for this tag
   at this location, typically for use by
   .Dv NODE_HREF ,
   so the existing integer, if any, is used without incrementing it.
 .Pp  .Pp
 The function  The function
 .Fn html_strlen  .Fn print_otag_id
 counts the number of characters in  opens a
 .Fa cp .  .Fa tag
 It is used as a crude estimate of the width needed to display a string.  element of class
   .Fa cattr
   for the node
   .Fa n .
   If the flag
   .Dv NODE_ID
   is set in
   .Fa n ,
   it attempts to generate an
   .Cm id
   attribute with
   .Fn html_make_id .
   If the flag
   .Dv NODE_HREF
   is set in
   .Fa n ,
   an
   .Aq Ic A
   element of class
   .Qq permalink
   is added:
   outside if
   .Fa n
   generates an element that can only occur in phrasing context,
   or inside otherwise.
   This function is a wrapper around
   .Fn html_make_id
   and
   .Fn print_otag ,
   automatically chosing the
   .Fa unique
   argument appropriately and setting the
   .Fa fmt
   arguments to
   .Qq chR
   and
   .Qq ci ,
   respectively.
 .Pp  .Pp
   The function
   .Fn print_endline
   makes sure subsequent output starts on a new HTML output line.
   If nothing was printed on the current output line yet, it has no effect.
   Otherwise, it appends any buffered text to the current output line,
   ends the line, and updates the internal state of the
   .Fa h
   object.
   .Pp
 The functions  The functions
 .Fn print_eqn ,  .Fn print_eqn ,
 .Fn print_tbl ,  .Fn print_tbl ,
 and  and
 .Fn print_tblclose  .Fn print_tblclose
 are not yet documented.  are not yet documented.
   .Sh RETURN VALUES
   The functions
   .Fn print_otag
   and
   .Fn print_otag_id
   return a pointer to a new element on the stack of HTML elements.
   When
   .Fn print_otag_id
   opens two elements, a pointer to the outer one is returned.
   The memory pointed to is owned by the library and is automatically
   .Xr free 3 Ns d
   when
   .Fn print_tagq
   is called on it or when
   .Fn print_stagq
   is called on a parent element.
   .Pp
   The function
   .Fn html_fillmode
   returns
   .Dv ROFF_fi
   if fill mode was active before the call or
   .Dv ROFF_nf
   otherwise.
   .Pp
   The function
   .Fn html_make_id
   returns a newly allocated string or
   .Dv NULL
   if
   .Fa n
   lacks text data to create the attribute from.
   The caller is responsible for
   .Xr free 3 Ns ing
   the returned string after using it.
   .Pp
   In case of
   .Xr malloc 3
   failure, these functions do not return but call
   .Xr err 3 .
 .Sh FILES  .Sh FILES
 .Bl -tag -width mandoc_aux.c -compact  .Bl -tag -width mandoc_aux.c -compact
 .It Pa main.h  .It Pa main.h
Line 325  HTML formatter
Line 516  HTML formatter
 .It Pa eqn_html.c  .It Pa eqn_html.c
 .Xr eqn 7  .Xr eqn 7
 HTML formatter  HTML formatter
   .It Pa roff_html.c
   .Xr roff 7
   HTML formatter, handling requests like
   .Ic br ,
   .Ic ce ,
   .Ic fi ,
   .Ic ft ,
   .Ic nf ,
   .Ic rj ,
   and
   .Ic sp .
 .It Pa out.h  .It Pa out.h
 declarations of data types and private functions  declarations of data types and private functions
 for shared use by all mandoc formatters,  for shared use by all mandoc formatters,
Legend:
Removed from v.1.16  
changed lines
  Added in v.1.23
CVSweb