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

version 1.4, 2017/01/25 02:14:43 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 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"
   .Fa "int unique"
   .Fc
   .Ft struct tag *
   .Fo print_otag_id
   .Fa "struct html *h"
   .Fa "enum htmltag tag"
   .Fa "const char *cattr"
   .Fa "struct roff_node *n"
   .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 101  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 137  Most attributes require one
Line 163  Most attributes require one
 .Va char *  .Va char *
 argument which becomes the value of the attribute.  argument which becomes the value of the attribute.
 The arguments have to be given in the same order as the attribute letters.  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  .Bl -tag -width 1n -offset indent
 .It Cm c  .It Cm c
 Print a  Print a
Line 175  Print an arbitrary attribute.
Line 204  Print an arbitrary attribute.
 This format letter requires two  This format letter requires two
 .Vt char *  .Vt char *
 arguments, the attribute name and the value.  arguments, the attribute name and the value.
   The name must not be
   .Dv NULL .
 .It Cm s  .It Cm s
 Print a  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 require 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 on 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 v  
 Requires one  
 .Vt int  
 argument, interpreted as a vertical length in units of  
 .Dv SCALE_VS .  
 .It Cm w  
 Requires one  
 .Vt char *  
 argument, interpreted as an  
 .Xr mdoc 7 Ns -style  
 width specifier.  
 .It Cm W  
 Similar to  
 .Cm w ,  
 but makes the width negative by multiplying it with \(mi1.  
 .El  
 .Pp  
 Style name letters decide what to do with the preceding argument:  
 .Bl -tag -width 1n -offset indent  
 .It Cm b  
 Set  
 .Cm margin-bottom  
 to the given length.  
 .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 t  
 Set  
 .Cm margin-top  
 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 name must not be
   .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 291  and
Line 259  and
 .Fn print_tagq  .Fn print_tagq
 functions.  functions.
 .Pp  .Pp
   The function
   .Fn html_make_id
   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 string
   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
   is returned instead.
   If the
   .Fa unique
   argument is non-zero, deduplication is performed by appending an
   underscore and a decimal integer, if necessary.
   .Pp
   The function
   .Fn print_otag_id
   opens a
   .Fa tag
   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
 The functions  The functions
 .Fn html_strlen ,  
 .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_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
Line 340  implementation of common mandoc utility functions
Line 424  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.4  
changed lines
  Added in v.1.20
CVSweb