[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.10 and 1.20

version 1.10, 2017/07/15 17:57:51 version 1.20, 2020/03/13 15:32:28
Line 1 
Line 1 
 .\"     $Id$  .\"     $Id$
 .\"  .\"
 .\" Copyright (c) 2014, 2017 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
Line 51 
Line 53 
 .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
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The mandoc HTML formatter is not a formal library.  The mandoc HTML formatter is not a formal library.
Line 109  and
Line 115  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 153  the respective attribute is not written.
Line 171  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 198  Print a
Line 211  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 h  
 Requires one  
 .Vt int  
 argument, interpreted as a horizontal length in units of  
 .Dv SCALE_EN .  
 .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.  
 .It Cm w  
 Requires one  
 .Vt char *  
 argument, interpreted as an  
 .Xr mdoc 7 Ns -style  
 width specifier.  
 If the argument is  
 .Dv NULL ,  
 nothing is printed for this pair.  
 .Pp  
 The  
 .Cm w  
 argument type letter can optionally be followed by one, two, or three  
 modifier letters.  
 The modifier  
 .Cm *  
 suppresses printing of the pair if the argument matches 6n.  
 The modifier  
 .Cm +  
 increases the width by 20% to make even bold text fit  
 and adds three units for padding between columns.  
 The modifier  
 .Cm \-  
 makes the width negative by multiplying it with \-1.  
 .El  
 .Pp  
 Style name letters decide what to do with the preceding argument:  
 .Bl -tag -width 1n -offset indent  
 .It Cm h  
 Set  
 .Cm height  
 to the given length.  
 .It Cm i  
 Set  
 .Cm text-indent  
 to the given length.  
 .It Cm l  
 Set  
 .Cm margin-left  
 to the given length.  
 .It Cm w  
 Set  
 .Cm width  
 to the given length.  
 .It Cm W  
 Set  
 .Cm min-width  
 to the given length.  
 .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 314  functions.
Line 261  functions.
 .Pp  .Pp
 The function  The function
 .Fn html_make_id  .Fn html_make_id
 takes a node containing one or more text children  allocates a string to be used for the
 and returns a newly allocated string containing the concatenation  .Cm id
 of the child strings, with blanks replaced by underscores.  attribute of an HTML element and/or as a segment identifier for a URI in an
 If the node  .Aq Ic A
   element.
   If
 .Fa n  .Fa n
 contains any non-text child node,  contains a
 .Fn html_make_id  .Fa string
 returns  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.
 .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 an
   .Cm id
   attribute is written,
   .Fn print_otag_id
   also adds an
   .Aq Ic A
   element of class
   .Qq permalink :
   outside if
   .Fa n
   generates a phrasing element, or inside otherwise.
   This function is a wrapper around
   .Fn html_make_id
   and
   .Fn print_otag ,
   fixing the
   .Fa unique
   argument to 1 and the
   .Fa fmt
   arguments to
   .Qq chR
   and
   .Qq ci ,
   respectively.
 .Pp  .Pp
 The functions  The functions
 .Fn print_eqn ,  .Fn print_eqn ,
Line 338  The functions
Line 339  The functions
 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_make_id
   returns a newly allocated string or
   .Dv NULL
   if
   .Fa n
   lacks text data to create the attribute from.
   If the
   .Fa unique
   argument is 0, the caller is responsible for
   .Xr free 3 Ns ing
   the returned string after using it.
   If the
   .Fa unique
   argument is non-zero, the
   .Va id_unique
   ohash table is used for de-duplication and owns the returned string.
   In this case, it will be freed automatically by
   .Fn html_reset
   or
   .Fn html_free .
   .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
Legend:
Removed from v.1.10  
changed lines
  Added in v.1.20
CVSweb