*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
enum htmltag {
TAG_HTML,
TAG_HEAD,
TAG_BODY,
TAG_META,
TAG_TITLE,
TAG_DIV,
TAG_H1,
TAG_H2,
TAG_SPAN,
TAG_LINK,
TAG_BR,
TAG_A,
TAG_TABLE,
TAG_COLGROUP,
TAG_COL,
TAG_TR,
TAG_TD,
TAG_LI,
TAG_UL,
TAG_OL,
TAG_DL,
TAG_DT,
TAG_DD,
TAG_PRE,
TAG_VAR,
TAG_CITE,
TAG_B,
TAG_I,
TAG_CODE,
TAG_SMALL,
TAG_STYLE,
TAG_MATH,
TAG_MROW,
TAG_MI,
TAG_MN,
TAG_MO,
TAG_MSUP,
TAG_MSUB,
TAG_MSUBSUP,
TAG_MFRAC,
TAG_MSQRT,
TAG_MFENCED,
TAG_MTABLE,
TAG_MTR,
TAG_MTD,
TAG_MUNDEROVER,
TAG_MUNDER,
TAG_MOVER,
TAG_MAX
};
enum htmlfont {
HTMLFONT_NONE = 0,
HTMLFONT_BOLD,
HTMLFONT_ITALIC,
HTMLFONT_BI,
HTMLFONT_MAX
};
struct tag {
struct tag *next;
enum htmltag tag;
};
struct html {
int flags;
#define HTML_NOSPACE (1 << 0) /* suppress next space */
#define HTML_IGNDELIM (1 << 1)
#define HTML_KEEP (1 << 2)
#define HTML_PREKEEP (1 << 3)
#define HTML_NONOSPACE (1 << 4) /* never add spaces */
#define HTML_LITERAL (1 << 5) /* literal (e.g., ) context */
#define HTML_SKIPCHAR (1 << 6) /* skip the next character */
#define HTML_NOSPLIT (1 << 7) /* do not break line before .An */
#define HTML_SPLIT (1 << 8) /* break line before .An */
#define HTML_NONEWLINE (1 << 9) /* No line break in nofill mode. */
#define HTML_BUFFER (1 << 10) /* Collect a word to see if it fits. */
size_t indent; /* current output indentation level */
int noindent; /* indent disabled by */
size_t col; /* current output byte position */
size_t bufcol; /* current buf byte position */
char buf[80]; /* output buffer */
struct tag *tag; /* last open tag */
struct rofftbl tbl; /* current table */
struct tag *tblt; /* current open table scope */
char *base_man; /* base for manpage href */
char *base_includes; /* base for include href */
char *style; /* style-sheet URI */
struct tag *metaf; /* current open font scope */
enum htmlfont metal; /* last used font */
enum htmlfont metac; /* current font mode */
int oflags; /* output options */
#define HTML_FRAGMENT (1 << 0) /* don't emit HTML/HEAD/BODY */
};
struct roff_node;
struct tbl_span;
struct eqn_box;
void roff_html_pre(struct html *, const struct roff_node *);
void print_gen_decls(struct html *);
void print_gen_head(struct html *);
struct tag *print_otag(struct html *, enum htmltag, const char *, ...);
void print_tagq(struct html *, const struct tag *);
void print_stagq(struct html *, const struct tag *);
void print_text(struct html *, const char *);
void print_tblclose(struct html *);
void print_tbl(struct html *, const struct tbl_span *);
void print_eqn(struct html *, const struct eqn_box *);
void print_paragraph(struct html *);
void print_endline(struct html *);
char *html_make_id(const struct roff_node *);
int html_strlen(const char *);
mandoc-1.14.3/lib.in 0100644 0002007 0000011 00000020052 13141336265 0013552 0 ustar 00schwarze wsrc /* $Id: lib.in,v 1.19 2016/11/23 20:22:13 schwarze Exp $ */
/*
* Copyright (c) 2009 Kristaps Dzonsons
* Copyright (c) 2009, 2012 Joerg Sonnenberger
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
/*
* These are all possible .Lb strings. When a new library is added, add
* its short-string to the left-hand side and formatted string to the
* right-hand side.
*
* Be sure to escape strings.
*/
LINE("libalias", "Packet Aliasing Library (libalias, \\-lalias)")
LINE("libarchive", "Streaming Archive Library (libarchive, \\-larchive)")
LINE("libarm", "ARM Architecture Library (libarm, \\-larm)")
LINE("libarm32", "ARM32 Architecture Library (libarm32, \\-larm32)")
LINE("libbluetooth", "Bluetooth Library (libbluetooth, \\-lbluetooth)")
LINE("libbsdxml", "eXpat XML parser library (libbsdxml, \\-lbsdxml)")
LINE("libbsm", "Basic Security Module User Library (libbsm, \\-lbsm)")
LINE("libc", "Standard C Library (libc, \\-lc)")
LINE("libc_r", "Reentrant C\\~Library (libc_r, \\-lc_r)")
LINE("libcalendar", "Calendar Arithmetic Library (libcalendar, \\-lcalendar)")
LINE("libcam", "Common Access Method User Library (libcam, \\-lcam)")
LINE("libcdk", "Curses Development Kit Library (libcdk, \\-lcdk)")
LINE("libcipher", "FreeSec Crypt Library (libcipher, \\-lcipher)")
LINE("libcompat", "Compatibility Library (libcompat, \\-lcompat)")
LINE("libcrypt", "Crypt Library (libcrypt, \\-lcrypt)")
LINE("libcurses", "Curses Library (libcurses, \\-lcurses)")
LINE("libdevattr", "Device attribute and event library (libdevattr, \\-ldevattr)")
LINE("libdevinfo", "Device and Resource Information Utility Library (libdevinfo, \\-ldevinfo)")
LINE("libdevstat", "Device Statistics Library (libdevstat, \\-ldevstat)")
LINE("libdisk", "Interface to Slice and Partition Labels Library (libdisk, \\-ldisk)")
LINE("libdm", "Device Mapper Library (libdm, \\-ldm)")
LINE("libdwarf", "DWARF Access Library (libdwarf, \\-ldwarf)")
LINE("libedit", "Command Line Editor Library (libedit, \\-ledit)")
LINE("libefi", "EFI Runtime Services Library (libefi, \\-lefi)")
LINE("libelf", "ELF Access Library (libelf, \\-lelf)")
LINE("libevent", "Event Notification Library (libevent, \\-levent)")
LINE("libexecinfo", "Backtrace Information Library (libexecinfo, \\-lexecinfo)")
LINE("libfetch", "File Transfer Library (libfetch, \\-lfetch)")
LINE("libfsid", "Filesystem Identification Library (libfsid, \\-lfsid)")
LINE("libftpio", "FTP Connection Management Library (libftpio, \\-lftpio)")
LINE("libform", "Curses Form Library (libform, \\-lform)")
LINE("libgeom", "Userland API Library for Kernel GEOM subsystem (libgeom, \\-lgeom)")
LINE("libgpib", "General-Purpose Instrument Bus (GPIB) library (libgpib, \\-lgpib)")
LINE("libhammer", "HAMMER Filesystem Userland Library (libhammer, \\-lhammer)")
LINE("libi386", "i386 Architecture Library (libi386, \\-li386)")
LINE("libintl", "Internationalized Message Handling Library (libintl, \\-lintl)")
LINE("libipsec", "IPsec Policy Control Library (libipsec, \\-lipsec)")
LINE("libipx", "IPX Address Conversion Support Library (libipx, \\-lipx)")
LINE("libiscsi", "iSCSI protocol library (libiscsi, \\-liscsi)")
LINE("libisns", "Internet Storage Name Service Library (libisns, \\-lisns)")
LINE("libjail", "Jail Library (libjail, \\-ljail)")
LINE("libkcore", "Kernel Memory Core Access Library (libkcore, \\-lkcore)")
LINE("libkiconv", "Kernel-side iconv Library (libkiconv, \\-lkiconv)")
LINE("libkse", "N:M Threading Library (libkse, \\-lkse)")
LINE("libkvm", "Kernel Data Access Library (libkvm, \\-lkvm)")
LINE("libm", "Math Library (libm, \\-lm)")
LINE("libm68k", "m68k Architecture Library (libm68k, \\-lm68k)")
LINE("libmagic", "Magic Number Recognition Library (libmagic, \\-lmagic)")
LINE("libmandoc", "Mandoc Macro Compiler Library (libmandoc, \\-lmandoc)")
LINE("libmd", "Message Digest (MD4, MD5, etc.) Support Library (libmd, \\-lmd)")
LINE("libmemstat", "Kernel Memory Allocator Statistics Library (libmemstat, \\-lmemstat)")
LINE("libmenu", "Curses Menu Library (libmenu, \\-lmenu)")
LINE("libmj", "Minimalist JSON library (libmj, \\-lmj)")
LINE("libnetgraph", "Netgraph User Library (libnetgraph, \\-lnetgraph)")
LINE("libnetpgp", "Netpgp Signing, Verification, Encryption and Decryption (libnetpgp, \\-lnetpgp)")
LINE("libnetpgpverify", "Netpgp Verification (libnetpgpverify, \\-lnetpgpverify)")
LINE("libnpf", "NPF Packet Filter Library (libnpf, \\-lnpf)")
LINE("libossaudio", "OSS Audio Emulation Library (libossaudio, \\-lossaudio)")
LINE("libpam", "Pluggable Authentication Module Library (libpam, \\-lpam)")
LINE("libpanel", "Z-order for curses windows (libpanel, \\-lpanel)")
LINE("libpcap", "Capture Library (libpcap, \\-lpcap)")
LINE("libpci", "PCI Bus Access Library (libpci, \\-lpci)")
LINE("libpmc", "Performance Counters Library (libpmc, \\-lpmc)")
LINE("libppath", "Property-List Paths Library (libppath, \\-lppath)")
LINE("libposix", "POSIX Compatibility Library (libposix, \\-lposix)")
LINE("libposix1e", "POSIX.1e Security API Library (libposix1e, \\-lposix1e)")
LINE("libppath", "Property-List Paths Library (libppath, \\-lppath)")
LINE("libproc", "Process Manipulation Library (libproc, \\-lproc)")
LINE("libprop", "Property Container Object Library (libprop, \\-lprop)")
LINE("libpthread", "POSIX Threads Library (libpthread, \\-lpthread)")
LINE("libpthread_dbg", "POSIX Debug Threads Library (libpthread_dbg, \\-lpthread_dbg)")
LINE("libpuffs", "puffs Convenience Library (libpuffs, \\-lpuffs)")
LINE("libquota", "Disk Quota Access and Control Library (libquota, \\-lquota)")
LINE("libradius", "RADIUS Client Library (libradius, \\-lradius)")
LINE("librefuse", "File System in Userspace Convenience Library (librefuse, \\-lrefuse)")
LINE("libresolv", "DNS Resolver Library (libresolv, \\-lresolv)")
LINE("librpcsec_gss", "RPC GSS-API Authentication Library (librpcsec_gss, \\-lrpcsec_gss)")
LINE("librpcsvc", "RPC Service Library (librpcsvc, \\-lrpcsvc)")
LINE("librt", "POSIX Real\\-time Library (librt, \\-lrt)")
LINE("librtld_db", "Debugging interface to the runtime linker Library (librtld_db, \\-lrtld_db)")
LINE("librumpclient", "Clientside Stubs for rump Kernel Remote Protocols (librumpclient, \\-lrumpclient)")
LINE("libsaslc", "Simple Authentication and Security Layer client library (libsaslc, \\-lsaslc)")
LINE("libsdp", "Bluetooth Service Discovery Protocol User Library (libsdp, \\-lsdp)")
LINE("libssp", "Buffer Overflow Protection Library (libssp, \\-lssp)")
LINE("libstand", "Standalone Applications Library (libstand, \\-lstand)")
LINE("libSystem", "System Library (libSystem, \\-lSystem)")
LINE("libtacplus", "TACACS+ Client Library (libtacplus, \\-ltacplus)")
LINE("libtcplay", "TrueCrypt-compatible API library (libtcplay, \\-ltcplay)")
LINE("libtermcap", "Termcap Access Library (libtermcap, \\-ltermcap)")
LINE("libterminfo", "Terminal Information Library (libterminfo, \\-lterminfo)")
LINE("libthr", "1:1 Threading Library (libthr, \\-lthr)")
LINE("libufs", "UFS File System Access Library (libufs, \\-lufs)")
LINE("libugidfw", "File System Firewall Interface Library (libugidfw, \\-lugidfw)")
LINE("libulog", "User Login Record Library (libulog, \\-lulog)")
LINE("libusbhid", "USB Human Interface Devices Library (libusbhid, \\-lusbhid)")
LINE("libutil", "System Utilities Library (libutil, \\-lutil)")
LINE("libvgl", "Video Graphics Library (libvgl, \\-lvgl)")
LINE("libx86_64", "x86_64 Architecture Library (libx86_64, \\-lx86_64)")
LINE("libz", "Compression Library (libz, \\-lz)")
mandoc-1.14.3/libman.h 0100644 0002007 0000011 00000003133 13141336265 0014070 0 ustar 00schwarze wsrc /* $Id: libman.h,v 1.81 2017/04/29 12:45:41 schwarze Exp $ */
/*
* Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons
* Copyright (c) 2014, 2015 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#define MACRO_PROT_ARGS struct roff_man *man, \
enum roff_tok tok, \
int line, \
int ppos, \
int *pos, \
char *buf
struct man_macro {
void (*fp)(MACRO_PROT_ARGS);
int flags;
#define MAN_SCOPED (1 << 0) /* Optional next-line scope. */
#define MAN_NSCOPED (1 << 1) /* Allowed in next-line element scope. */
#define MAN_BSCOPE (1 << 2) /* Break next-line block scope. */
#define MAN_JOIN (1 << 3) /* Join arguments together. */
};
extern const struct man_macro *const man_macros;
void man_node_validate(struct roff_man *);
void man_state(struct roff_man *, struct roff_node *);
void man_unscope(struct roff_man *, const struct roff_node *);
mandoc-1.14.3/libmandoc.h 0100644 0002007 0000011 00000005404 13141336265 0014561 0 ustar 00schwarze wsrc /* $Id: libmandoc.h,v 1.70 2017/07/08 17:52:49 schwarze Exp $ */
/*
* Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons
* Copyright (c) 2013, 2014, 2015, 2017 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
enum rofferr {
ROFF_CONT, /* continue processing line */
ROFF_RERUN, /* re-run roff interpreter with offset */
ROFF_APPEND, /* re-run main parser, appending next line */
ROFF_REPARSE, /* re-run main parser on the result */
ROFF_SO, /* include another file */
ROFF_IGN, /* ignore current line */
};
struct buf {
char *buf;
size_t sz;
};
struct mparse;
struct roff;
struct roff_man;
void mandoc_msg(enum mandocerr, struct mparse *,
int, int, const char *);
void mandoc_vmsg(enum mandocerr, struct mparse *,
int, int, const char *, ...)
__attribute__((__format__ (__printf__, 5, 6)));
char *mandoc_getarg(struct mparse *, char **, int, int *);
char *mandoc_normdate(struct roff_man *, char *, int, int);
int mandoc_eos(const char *, size_t);
int mandoc_strntoi(const char *, size_t, int);
const char *mandoc_a2msec(const char*);
int mdoc_parseln(struct roff_man *, int, char *, int);
void mdoc_endparse(struct roff_man *);
int man_parseln(struct roff_man *, int, char *, int);
void man_endparse(struct roff_man *);
int preconv_cue(const struct buf *, size_t);
int preconv_encode(const struct buf *, size_t *,
struct buf *, size_t *, int *);
void roff_free(struct roff *);
struct roff *roff_alloc(struct mparse *, int);
void roff_reset(struct roff *);
void roff_man_free(struct roff_man *);
struct roff_man *roff_man_alloc(struct roff *, struct mparse *,
const char *, int);
void roff_man_reset(struct roff_man *);
enum rofferr roff_parseln(struct roff *, int, struct buf *, int *);
void roff_endparse(struct roff *);
void roff_setreg(struct roff *, const char *, int, char sign);
int roff_getreg(const struct roff *, const char *);
char *roff_strdup(const struct roff *, const char *);
int roff_getcontrol(const struct roff *,
const char *, int *);
int roff_getformat(const struct roff *);
mandoc-1.14.3/libmdoc.h 0100644 0002007 0000011 00000006070 13141336265 0014242 0 ustar 00schwarze wsrc /* $Id: libmdoc.h,v 1.112 2017/05/30 16:22:03 schwarze Exp $ */
/*
* Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons
* Copyright (c) 2013, 2014, 2015, 2017 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#define MACRO_PROT_ARGS struct roff_man *mdoc, \
enum roff_tok tok, \
int line, \
int ppos, \
int *pos, \
char *buf
struct mdoc_macro {
void (*fp)(MACRO_PROT_ARGS);
int flags;
#define MDOC_CALLABLE (1 << 0)
#define MDOC_PARSED (1 << 1)
#define MDOC_EXPLICIT (1 << 2)
#define MDOC_PROLOGUE (1 << 3)
#define MDOC_IGNDELIM (1 << 4)
#define MDOC_JOIN (1 << 5)
};
enum margserr {
ARGS_ERROR,
ARGS_EOLN, /* end-of-line */
ARGS_WORD, /* normal word */
ARGS_PUNCT, /* series of punctuation */
ARGS_PHRASE /* Bl -column phrase */
};
/*
* A punctuation delimiter is opening, closing, or "middle mark"
* punctuation. These govern spacing.
* Opening punctuation (e.g., the opening parenthesis) suppresses the
* following space; closing punctuation (e.g., the closing parenthesis)
* suppresses the leading space; middle punctuation (e.g., the vertical
* bar) can do either. The middle punctuation delimiter bends the rules
* depending on usage.
*/
enum mdelim {
DELIM_NONE = 0,
DELIM_OPEN,
DELIM_MIDDLE,
DELIM_CLOSE,
DELIM_MAX
};
extern const struct mdoc_macro *const mdoc_macros;
void mdoc_macro(MACRO_PROT_ARGS);
void mdoc_elem_alloc(struct roff_man *, int, int,
enum roff_tok, struct mdoc_arg *);
struct roff_node *mdoc_block_alloc(struct roff_man *, int, int,
enum roff_tok, struct mdoc_arg *);
void mdoc_tail_alloc(struct roff_man *, int, int,
enum roff_tok);
struct roff_node *mdoc_endbody_alloc(struct roff_man *, int, int,
enum roff_tok, struct roff_node *);
void mdoc_node_relink(struct roff_man *, struct roff_node *);
void mdoc_node_validate(struct roff_man *);
void mdoc_state(struct roff_man *, struct roff_node *);
void mdoc_state_reset(struct roff_man *);
const char *mdoc_a2arch(const char *);
const char *mdoc_a2att(const char *);
const char *mdoc_a2lib(const char *);
enum roff_sec mdoc_a2sec(const char *);
const char *mdoc_a2st(const char *);
void mdoc_argv(struct roff_man *, int, enum roff_tok,
struct mdoc_arg **, int *, char *);
enum margserr mdoc_args(struct roff_man *, int,
int *, char *, enum roff_tok, char **);
enum mdelim mdoc_isdelim(const char *);
mandoc-1.14.3/libroff.h 0100644 0002007 0000011 00000006025 13141336265 0014254 0 ustar 00schwarze wsrc /* $Id: libroff.h,v 1.42 2017/07/08 17:52:49 schwarze Exp $ */
/*
* Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons
* Copyright (c) 2014, 2015, 2017 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
enum tbl_part {
TBL_PART_OPTS, /* in options (first line) */
TBL_PART_LAYOUT, /* describing layout */
TBL_PART_DATA, /* creating data rows */
TBL_PART_CDATA /* continue previous row */
};
struct tbl_node {
struct mparse *parse; /* parse point */
int pos; /* invocation column */
int line; /* invocation line */
enum tbl_part part;
struct tbl_opts opts;
struct tbl_row *first_row;
struct tbl_row *last_row;
struct tbl_span *first_span;
struct tbl_span *current_span;
struct tbl_span *last_span;
struct tbl_node *next;
};
struct eqn_node {
struct mparse *parse; /* main parser, for error reporting */
struct roff_node *node; /* syntax tree of this equation */
struct eqn_def *defs; /* array of definitions */
char *data; /* source code of this equation */
char *start; /* first byte of the current token */
char *end; /* first byte of the next token */
size_t defsz; /* number of definitions */
size_t sz; /* length of the source code */
size_t toksz; /* length of the current token */
int gsize; /* default point size */
int delim; /* in-line delimiters enabled */
char odelim; /* in-line opening delimiter */
char cdelim; /* in-line closing delimiter */
};
struct eqn_def {
char *key;
size_t keysz;
char *val;
size_t valsz;
};
struct tbl_node *tbl_alloc(int, int, struct mparse *);
void tbl_restart(int, int, struct tbl_node *);
void tbl_free(struct tbl_node *);
void tbl_reset(struct tbl_node *);
void tbl_read(struct tbl_node *, int, const char *, int);
void tbl_option(struct tbl_node *, int, const char *, int *);
void tbl_layout(struct tbl_node *, int, const char *, int);
void tbl_data(struct tbl_node *, int, const char *, int);
void tbl_cdata(struct tbl_node *, int, const char *, int);
const struct tbl_span *tbl_span(struct tbl_node *);
int tbl_end(struct tbl_node *);
struct eqn_node *eqn_alloc(struct mparse *);
void eqn_box_free(struct eqn_box *);
void eqn_free(struct eqn_node *);
void eqn_parse(struct eqn_node *);
void eqn_read(struct eqn_node *, const char *);
void eqn_reset(struct eqn_node *);
mandoc-1.14.3/main.h 0100644 0002007 0000011 00000004105 13141336265 0013552 0 ustar 00schwarze wsrc /* $Id: main.h,v 1.27 2017/03/03 14:23:23 schwarze Exp $ */
/*
* Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons
* Copyright (c) 2014, 2015 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
struct roff_man;
struct manoutput;
/*
* Definitions for main.c-visible output device functions, e.g., -Thtml
* and -Tascii. Note that ascii_alloc() is named as such in
* anticipation of latin1_alloc() and so on, all of which map into the
* terminal output routines with different character settings.
*/
void *html_alloc(const struct manoutput *);
void html_mdoc(void *, const struct roff_man *);
void html_man(void *, const struct roff_man *);
void html_free(void *);
void tree_mdoc(void *, const struct roff_man *);
void tree_man(void *, const struct roff_man *);
void man_mdoc(void *, const struct roff_man *);
void man_man(void *, const struct roff_man *);
void *locale_alloc(const struct manoutput *);
void *utf8_alloc(const struct manoutput *);
void *ascii_alloc(const struct manoutput *);
void ascii_free(void *);
void *pdf_alloc(const struct manoutput *);
void *ps_alloc(const struct manoutput *);
void pspdf_free(void *);
void terminal_mdoc(void *, const struct roff_man *);
void terminal_man(void *, const struct roff_man *);
void terminal_sepline(void *);
void markdown_mdoc(void *, const struct roff_man *);
mandoc-1.14.3/makewhatis.8 0100644 0002007 0000011 00000011441 13141336265 0014704 0 ustar 00schwarze wsrc .\" $Id: makewhatis.8,v 1.6 2017/05/17 22:27:12 schwarze Exp $
.\"
.\" Copyright (c) 2011, 2012 Kristaps Dzonsons
.\" Copyright (c) 2011, 2012, 2014, 2017 Ingo Schwarze
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: May 17 2017 $
.Dt MAKEWHATIS 8
.Os
.Sh NAME
.Nm makewhatis
.Nd index UNIX manuals
.Sh SYNOPSIS
.Nm
.Op Fl aDnpQ
.Op Fl T Cm utf8
.Op Fl C Ar file
.Nm
.Op Fl aDnpQ
.Op Fl T Cm utf8
.Ar dir ...
.Nm
.Op Fl DnpQ
.Op Fl T Cm utf8
.Fl d Ar dir
.Op Ar
.Nm
.Op Fl Dnp
.Op Fl T Cm utf8
.Fl u Ar dir
.Op Ar
.Nm
.Op Fl DQ
.Fl t Ar
.Sh DESCRIPTION
The
.Nm
utility extracts keywords from
.Ux
manuals and indexes them in a database for fast retrieval by
.Xr apropos 1 ,
.Xr whatis 1 ,
and
.Xr man 1 Ns 's
.Fl k
option.
.Pp
By default,
.Nm
creates a database in each
.Ar dir
using the files
.Sm off
.Sy man Ar section Li /
.Op Ar arch Li /
.Ar title . section
.Sm on
and
.Sm off
.Sy cat Ar section Li /
.Op Ar arch Li /
.Ar title . Sy 0
.Sm on
in that directory.
Existing databases are replaced.
If a directory contains no manual pages, no database is created in that
directory.
If
.Ar dir
is not provided,
.Nm
uses the default paths stipulated by
.Xr man.conf 5 .
.Pp
The arguments are as follows:
.Bl -tag -width "-C file"
.It Fl a
Use all directories and files found below
.Ar dir ... .
.It Fl C Ar file
Specify an alternative configuration
.Ar file
in
.Xr man.conf 5
format.
.It Fl D
Display all files added or removed to the index.
With a second
.Fl D ,
also show all keywords added for each file.
.It Fl d Ar dir
Merge (remove and re-add)
.Ar
to the database in
.Ar dir .
.It Fl n
Do not create or modify any database; scan and parse only,
and print manual page names and descriptions to standard output.
.It Fl p
Print warnings about potential problems with manual pages
to the standard error output.
.It Fl Q
Quickly build reduced-size databases
by reading only the NAME sections of manuals.
The resulting databases will usually contain names and descriptions only.
.It Fl T Cm utf8
Use UTF-8 encoding instead of ASCII for strings stored in the databases.
.It Fl t Ar
Check the given
.Ar files
for potential problems.
Implies
.Fl a ,
.Fl n ,
and
.Fl p .
All diagnostic messages are printed to the standard output;
the standard error output is not used.
.It Fl u Ar dir
Remove
.Ar
from the database in
.Ar dir .
If that causes the database to become empty, also delete the database file.
.El
.Pp
If fatal parse errors are encountered while parsing, the offending file
is printed to stderr, omitted from the index, and the parse continues
with the next input file.
.Sh ENVIRONMENT
.Bl -tag -width MANPATH
.It Ev MANPATH
A colon-separated list of directories to create databases in.
Ignored if a
.Ar dir
argument or the
.Fl t
option is specified.
.El
.Sh FILES
.Bl -tag -width Ds
.It Pa mandoc.db
A database of manpages relative to the directory of the file.
This file is portable across architectures and systems, so long as the
manpage hierarchy it indexes does not change.
.It Pa /etc/man.conf
The default
.Xr man 1
configuration file.
.El
.Sh EXIT STATUS
The
.Nm
utility exits with one of the following values:
.Pp
.Bl -tag -width Ds -compact
.It 0
No errors occurred.
.It 5
Invalid command line arguments were specified.
No input files have been read.
.It 6
An operating system error occurred, for example memory exhaustion or an
error accessing input files.
Such errors cause
.Nm
to exit at once, possibly in the middle of parsing or formatting a file.
The output databases are corrupt and should be removed.
.El
.Sh SEE ALSO
.Xr apropos 1 ,
.Xr man 1 ,
.Xr whatis 1 ,
.Xr man.conf 5
.Sh HISTORY
A
.Nm
utility first appeared in
.Bx 2 .
It was rewritten in
.Xr perl 1
for
.Ox 2.7
and in C for
.Ox 5.6 .
.Pp
The
.Ar dir
argument first appeared in
.Nx 1.0 ;
the options
.Fl dpt
in
.Ox 2.7 ;
the option
.Fl u
in
.Ox 3.4 ;
and the options
.Fl aCDnQT
in
.Ox 5.6 .
.Sh AUTHORS
.An -nosplit
.An Bill Joy
wrote the original
.Bx
.Nm
in February 1979,
.An Marc Espie
started the Perl version in 2000,
and the current version of
.Nm
was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
and
.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
mandoc-1.14.3/man.1 0100644 0002007 0000011 00000020651 13141336265 0013316 0 ustar 00schwarze wsrc .\" $Id: man.1,v 1.29 2017/05/17 23:23:00 schwarze Exp $
.\"
.\" Copyright (c) 1989, 1990, 1993
.\" The Regents of the University of California. All rights reserved.
.\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre
.\" Copyright (c) 2010, 2011, 2014-2017 Ingo Schwarze
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)man.1 8.2 (Berkeley) 1/2/94
.\"
.Dd $Mdocdate: May 17 2017 $
.Dt MAN 1
.Os
.Sh NAME
.Nm man
.Nd display manual pages
.Sh SYNOPSIS
.Nm man
.Op Fl acfhklw
.Op Fl C Ar file
.Op Fl M Ar path
.Op Fl m Ar path
.Op Fl S Ar subsection
.Op Oo Fl s Oc Ar section
.Ar name ...
.Sh DESCRIPTION
The
.Nm
utility
displays the
manual pages entitled
.Ar name .
Pages may be selected according to
a specific category
.Pq Ar section
or
machine architecture
.Pq Ar subsection .
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl a
Display all matching manual pages.
Normally, only the first page found is displayed.
.It Fl C Ar file
Use the specified
.Ar file
instead of the default configuration file.
This permits users to configure their own manual environment.
See
.Xr man.conf 5
for a description of the contents of this file.
.It Fl c
Copy the manual page to the standard output instead of using
.Xr more 1
to paginate it.
This is done by default if the standard output is not a terminal device.
.It Fl f
A synonym for
.Xr whatis 1 .
It searches for
.Ar name
in manual page names and displays the header lines from all matching pages.
The search is case insensitive and matches whole words only.
.It Fl h
Display only the SYNOPSIS lines of the requested manual pages.
Implies
.Fl a
and
.Fl c .
.It Fl k
A synonym for
.Xr apropos 1 .
Instead of
.Ar name ,
an expression can be provided using the syntax described in the
.Xr apropos 1
manual.
By default, it displays the header lines of all matching pages.
.It Fl l
A synonym for
.Xr mandoc 1
.Fl a .
The
.Ar name
arguments are interpreted as filenames.
No search is done and
.Ar file ,
.Ar path ,
.Ar section ,
.Ar subsection ,
and
.Fl w
are ignored.
.It Fl M Ar path
Override the list of standard directories which
.Nm
searches for manual pages.
The supplied
.Ar path
must be a colon
.Pq Ql \&:
separated list of directories.
This search path may also be set using the environment variable
.Ev MANPATH .
.It Fl m Ar path
Augment the list of standard directories which
.Nm
searches for manual pages.
The supplied
.Ar path
must be a colon
.Pq Ql \&:
separated list of directories.
These directories will be searched before the standard directories or
the directories specified using the
.Fl M
option or the
.Ev MANPATH
environment variable.
.It Fl S Ar subsection
Only show pages for the specified
.Xr machine 1
architecture.
.Ar subsection
is case insensitive.
.Pp
By default manual pages for all architectures are installed.
Therefore this option can be used to view pages for one
architecture whilst using another.
.Pp
This option overrides the
.Ev MACHINE
environment variable.
.It Oo Fl s Oc Ar section
Only select manuals from the specified
.Ar section .
The currently available sections are:
.Pp
.Bl -tag -width "localXXX" -offset indent -compact
.It 1
General commands
.Pq tools and utilities .
.It 2
System calls and error numbers.
.It 3
Library functions.
.It 3p
.Xr perl 1
programmer's reference guide.
.It 4
Device drivers.
.It 5
File formats.
.It 6
Games.
.It 7
Miscellaneous information.
.It 8
System maintenance and operation commands.
.It 9
Kernel internals.
.El
.Pp
If not specified and a match is found in more than one section,
the first match is selected from the following list:
1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
.It Fl w
List the pathnames of all matching manual pages instead of displaying
any of them.
.El
.Pp
The options
.Fl IKOTW
are also supported and are documented in
.Xr mandoc 1 .
The options
.Fl fkl
are mutually exclusive and override each other.
.Pp
Guidelines for writing
man pages can be found in
.Xr mdoc 7 .
.Pp
If both a formatted and an unformatted version of the same manual page,
for example
.Pa cat1/foo.0
and
.Pa man1/foo.1 ,
exist in the same directory, only the unformatted version is used.
.Sh ENVIRONMENT
.Bl -tag -width MANPATHX
.It Ev MACHINE
As some manual pages are intended only for specific architectures,
.Nm
searches any subdirectories,
with the same name as the current architecture,
in every directory which it searches.
Machine specific areas are checked before general areas.
The current machine type may be overridden by setting the environment
variable
.Ev MACHINE
to the name of a specific architecture,
or with the
.Fl S
option.
.Ev MACHINE
is case insensitive.
.It Ev MANPAGER
Any non-empty value of the environment variable
.Ev MANPAGER
is used instead of the standard pagination program,
.Xr more 1 .
If
.Xr less 1
is used, the interactive
.Ic :t
command can be used to go to the definitions of various terms, for
example command line options, command modifiers, internal commands,
environment variables, function names, preprocessor macros,
.Xr errno 2
values, and some other emphasized words.
Some terms may have defining text at more than one place.
In that case, the
.Xr less 1
interactive commands
.Ic t
and
.Ic T
can be used to move to the next and to the previous place providing
information about the term last searched for with
.Ic :t .
.It Ev MANPATH
The standard search path used by
.Nm
may be changed by specifying a path in the
.Ev MANPATH
environment variable.
The format of the path is a colon
.Pq Ql \&:
separated list of directories.
Invalid paths are ignored.
Overridden by
.Fl M ,
ignored if
.Fl l
is specified.
.Pp
If
.Ev MANPATH
begins with a colon, it is appended to the default list;
if it ends with a colon, it is prepended to the default list;
or if it contains two adjacent colons,
the standard search path is inserted between the colons.
If none of these conditions are met, it overrides the
standard search path.
.It Ev PAGER
Specifies the pagination program to use when
.Ev MANPAGER
is not defined.
If neither PAGER nor MANPAGER is defined,
.Xr more 1
.Fl s
is used.
Only used if
.Fl a
or
.Fl l
is specified.
.El
.Sh FILES
.Bl -tag -width /etc/man.conf -compact
.It Pa /etc/man.conf
default man configuration file
.El
.Sh EXIT STATUS
.Ex -std man
See
.Xr mandoc 1
for details.
.Sh SEE ALSO
.Xr apropos 1 ,
.Xr intro 1 ,
.Xr whereis 1 ,
.Xr intro 2 ,
.Xr intro 3 ,
.Xr intro 4 ,
.Xr intro 5 ,
.Xr man.conf 5 ,
.Xr intro 6 ,
.Xr intro 7 ,
.Xr mdoc 7 ,
.Xr intro 8 ,
.Xr intro 9
.Sh STANDARDS
The
.Nm
utility is compliant with the
.St -p1003.1-2008
specification.
.Pp
The flags
.Op Fl aCcfhIKlMmOSsTWw ,
as well as the environment variables
.Ev MACHINE ,
.Ev MANPAGER ,
and
.Ev MANPATH ,
are extensions to that specification.
.Sh HISTORY
A
.Nm
command first appeared in
.At v3 .
.Pp
The
.Fl w
option first appeared in
.At v7 ;
.Fl f
and
.Fl k
in
.Bx 4 ;
.Fl M
in
.Bx 4.3 ;
.Fl a
in
.Bx 4.3 Tahoe ;
.Fl c
and
.Fl m
in
.Bx 4.3 Reno ;
.Fl h
in
.Bx 4.3 Net/2 ;
.Fl C
in
.Nx 1.0 ;
.Fl s
and
.Fl S
in
.Ox 2.3 ;
and
.Fl I ,
.Fl K ,
.Fl l ,
.Fl O ,
and
.Fl W
in
.Ox 5.7 .
The
.Fl T
option first appeared in
.At III
and was also added in
.Ox 5.7 .
mandoc-1.14.3/man.7 0100644 0002007 0000011 00000056236 13141336265 0013334 0 ustar 00schwarze wsrc .\" $Id: man.7,v 1.136 2017/06/25 11:42:02 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons
.\" Copyright (c) 2011-2015 Ingo Schwarze
.\" Copyright (c) 2010 Joerg Sonnenberger
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: June 25 2017 $
.Dt MAN 7
.Os
.Sh NAME
.Nm man
.Nd legacy formatting language for manual pages
.Sh DESCRIPTION
Traditionally, the
.Nm man
language has been used to write
.Ux
manuals for the
.Xr man 1
utility.
It supports limited control of presentational details like fonts,
indentation and spacing.
This reference document describes the structure of manual pages
and the syntax and usage of the man language.
.Pp
.Bf -emphasis
Do not use
.Nm
to write your manuals:
.Ef
It lacks support for semantic markup.
Use the
.Xr mdoc 7
language, instead.
.Pp
In a
.Nm
document, lines beginning with the control character
.Sq \&.
are called
.Dq macro lines .
The first word is the macro name.
It usually consists of two capital letters.
For a list of available macros, see
.Sx MACRO OVERVIEW .
The words following the macro name are arguments to the macro.
.Pp
Lines not beginning with the control character are called
.Dq text lines .
They provide free-form text to be printed; the formatting of the text
depends on the respective processing context:
.Bd -literal -offset indent
\&.SH Macro lines change control state.
Text lines are interpreted within the current state.
.Ed
.Pp
Many aspects of the basic syntax of the
.Nm
language are based on the
.Xr roff 7
language; see the
.Em LANGUAGE SYNTAX
and
.Em MACRO SYNTAX
sections in the
.Xr roff 7
manual for details, in particular regarding
comments, escape sequences, whitespace, and quoting.
.Sh MANUAL STRUCTURE
Each
.Nm
document must contain the
.Sx \&TH
macro describing the document's section and title.
It may occur anywhere in the document, although conventionally it
appears as the first macro.
.Pp
Beyond
.Sx \&TH ,
at least one macro or text line must appear in the document.
.Pp
The following is a well-formed skeleton
.Nm
file for a utility
.Qq progname :
.Bd -literal -offset indent
\&.TH PROGNAME 1 2009-10-10
\&.SH NAME
\efBprogname\efR \e(en one line about what it does
\&.\e\(dq .SH LIBRARY
\&.\e\(dq For sections 2, 3, and 9 only.
\&.\e\(dq Not used in OpenBSD.
\&.SH SYNOPSIS
\efBprogname\efR [\efB\e-options\efR] \efIfile ...\efR
\&.SH DESCRIPTION
The \efBfoo\efR utility processes files ...
\&.\e\(dq .Sh CONTEXT
\&.\e\(dq For section 9 functions only.
\&.\e\(dq .SH IMPLEMENTATION NOTES
\&.\e\(dq Not used in OpenBSD.
\&.\e\(dq .SH RETURN VALUES
\&.\e\(dq For sections 2, 3, and 9 function return values only.
\&.\e\(dq .SH ENVIRONMENT
\&.\e\(dq For sections 1, 6, 7, and 8 only.
\&.\e\(dq .SH FILES
\&.\e\(dq .SH EXIT STATUS
\&.\e\(dq For sections 1, 6, and 8 only.
\&.\e\(dq .SH EXAMPLES
\&.\e\(dq .SH DIAGNOSTICS
\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
\&.\e\(dq .SH ERRORS
\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only.
\&.\e\(dq .SH SEE ALSO
\&.\e\(dq .BR foobar ( 1 )
\&.\e\(dq .SH STANDARDS
\&.\e\(dq .SH HISTORY
\&.\e\(dq .SH AUTHORS
\&.\e\(dq .SH CAVEATS
\&.\e\(dq .SH BUGS
\&.\e\(dq .SH SECURITY CONSIDERATIONS
\&.\e\(dq Not used in OpenBSD.
.Ed
.Pp
The sections in a
.Nm
document are conventionally ordered as they appear above.
Sections should be composed as follows:
.Bl -ohang -offset indent
.It Em NAME
The name(s) and a short description of the documented material.
The syntax for this is generally as follows:
.Pp
.D1 \efBname\efR \e(en description
.It Em LIBRARY
The name of the library containing the documented material, which is
assumed to be a function in a section 2 or 3 manual.
For functions in the C library, this may be as follows:
.Pp
.D1 Standard C Library (libc, -lc)
.It Em SYNOPSIS
Documents the utility invocation syntax, function call syntax, or device
configuration.
.Pp
For the first, utilities (sections 1, 6, and 8), this is
generally structured as follows:
.Pp
.D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
.Pp
For the second, function calls (sections 2, 3, 9):
.Pp
.D1 \&.B char *name(char *\efIarg\efR);
.Pp
And for the third, configurations (section 4):
.Pp
.D1 \&.B name* at cardbus ? function ?
.Pp
Manuals not in these sections generally don't need a
.Em SYNOPSIS .
.It Em DESCRIPTION
This expands upon the brief, one-line description in
.Em NAME .
It usually contains a break-down of the options (if documenting a
command).
.It Em CONTEXT
This section lists the contexts in which functions can be called in section 9.
The contexts are autoconf, process, or interrupt.
.It Em IMPLEMENTATION NOTES
Implementation-specific notes should be kept here.
This is useful when implementing standard functions that may have side
effects or notable algorithmic implications.
.It Em RETURN VALUES
This section documents the return values of functions in sections 2, 3, and 9.
.It Em ENVIRONMENT
Documents any usages of environment variables, e.g.,
.Xr environ 7 .
.It Em FILES
Documents files used.
It's helpful to document both the file name and a short description of how
the file is used (created, modified, etc.).
.It Em EXIT STATUS
This section documents the command exit status for
section 1, 6, and 8 utilities.
Historically, this information was described in
.Em DIAGNOSTICS ,
a practise that is now discouraged.
.It Em EXAMPLES
Example usages.
This often contains snippets of well-formed,
well-tested invocations.
Make sure that examples work properly!
.It Em DIAGNOSTICS
Documents error conditions.
In section 4 and 9 manuals, these are usually messages
printed by the kernel to the console and to the kernel log.
In section 1, 6, 7, and 8, these are usually messages
printed by userland programs to the standard error output.
.Pp
Historically, this section was used in place of
.Em EXIT STATUS
for manuals in sections 1, 6, and 8; however, this practise is
discouraged.
.It Em ERRORS
Documents
.Xr errno 2
settings in sections 2, 3, 4, and 9.
.It Em SEE ALSO
References other manuals with related topics.
This section should exist for most manuals.
.Pp
.D1 \&.BR bar \&( 1 \&),
.Pp
Cross-references should conventionally be ordered
first by section, then alphabetically.
.It Em STANDARDS
References any standards implemented or used, such as
.Pp
.D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq)
.Pp
If not adhering to any standards, the
.Em HISTORY
section should be used.
.It Em HISTORY
A brief history of the subject, including where support first appeared.
.It Em AUTHORS
Credits to the person or persons who wrote the code and/or documentation.
Authors should generally be noted by both name and email address.
.It Em CAVEATS
Common misuses and misunderstandings should be explained
in this section.
.It Em BUGS
Known bugs, limitations, and work-arounds should be described
in this section.
.It Em SECURITY CONSIDERATIONS
Documents any security precautions that operators should consider.
.El
.Sh MACRO OVERVIEW
This overview is sorted such that macros of similar purpose are listed
together, to help find the best macro for any given purpose.
Deprecated macros are not included in the overview, but can be found
in the alphabetical reference below.
.Ss Page header and footer meta-data
.Bl -column "PP, LP, P" description
.It Sx TH Ta set the title: Ar title section date Op Ar source Op Ar volume
.It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
.It Sx UC Ta display BSD version in the page footer (<= 1 argument)
.El
.Ss Sections and paragraphs
.Bl -column "PP, LP, P" description
.It Sx SH Ta section header (one line)
.It Sx SS Ta subsection header (one line)
.It Sx PP , LP , P Ta start an undecorated paragraph (no arguments)
.It Sx RS , RE Ta reset the left margin: Op Ar width
.It Sx IP Ta indented paragraph: Op Ar head Op Ar width
.It Sx TP Ta tagged paragraph: Op Ar width
.It Sx HP Ta hanged paragraph: Op Ar width
.It Sx PD Ta set vertical paragraph distance: Op Ar height
.It Sx fi , nf Ta fill mode and no-fill mode (no arguments)
.It Sx in Ta additional indent: Op Ar width
.El
.Ss Physical markup
.Bl -column "PP, LP, P" description
.It Sx B Ta boldface font
.It Sx I Ta italic font
.It Sx R Ta roman (default) font
.It Sx SB Ta small boldface font
.It Sx SM Ta small roman font
.It Sx BI Ta alternate between boldface and italic fonts
.It Sx BR Ta alternate between boldface and roman fonts
.It Sx IB Ta alternate between italic and boldface fonts
.It Sx IR Ta alternate between italic and roman fonts
.It Sx RB Ta alternate between roman and boldface fonts
.It Sx RI Ta alternate between roman and italic fonts
.El
.Sh MACRO REFERENCE
This section is a canonical reference to all macros, arranged
alphabetically.
For the scoping of individual macros, see
.Sx MACRO SYNTAX .
.Ss \&AT
Sets the volume for the footer for compatibility with man pages from
.At
releases.
The optional arguments specify which release it is from.
.Ss \&B
Text is rendered in bold face.
.Pp
See also
.Sx \&I
and
.Sx \&R .
.Ss \&BI
Text is rendered alternately in bold face and italic.
Thus,
.Sq .BI this word and that
causes
.Sq this
and
.Sq and
to render in bold face, while
.Sq word
and
.Sq that
render in italics.
Whitespace between arguments is omitted in output.
.Pp
Examples:
.Pp
.Dl \&.BI bold italic bold italic
.Pp
The output of this example will be emboldened
.Dq bold
and italicised
.Dq italic ,
with spaces stripped between arguments.
.Pp
See also
.Sx \&IB ,
.Sx \&BR ,
.Sx \&RB ,
.Sx \&RI ,
and
.Sx \&IR .
.Ss \&BR
Text is rendered alternately in bold face and roman (the default font).
Whitespace between arguments is omitted in output.
.Pp
See
.Sx \&BI
for an equivalent example.
.Pp
See also
.Sx \&BI ,
.Sx \&IB ,
.Sx \&RB ,
.Sx \&RI ,
and
.Sx \&IR .
.Ss \&DT
Restore the default tabulator positions.
They are at intervals of 0.5 inches.
This has no effect unless the tabulator positions were changed with the
.Xr roff 7
.Ic \&ta
request.
.Ss \&EE
This is a non-standard GNU extension, included only for compatibility.
In
.Xr mandoc 1 ,
it does the same as
.Sx \&fi .
.Ss \&EX
This is a non-standard GNU extension, included only for compatibility.
In
.Xr mandoc 1 ,
it does the same as
.Sx \&nf .
.Ss \&HP
Begin a paragraph whose initial output line is left-justified, but
subsequent output lines are indented, with the following syntax:
.Bd -filled -offset indent
.Pf \. Sx \&HP
.Op Ar width
.Ed
.Pp
The
.Ar width
argument is a
.Xr roff 7
scaling width.
If specified, it's saved for later paragraph left-margins; if unspecified, the
saved or default width is used.
.Pp
See also
.Sx \&IP ,
.Sx \&LP ,
.Sx \&P ,
.Sx \&PP ,
and
.Sx \&TP .
.Ss \&I
Text is rendered in italics.
.Pp
See also
.Sx \&B
and
.Sx \&R .
.Ss \&IB
Text is rendered alternately in italics and bold face.
Whitespace between arguments is omitted in output.
.Pp
See
.Sx \&BI
for an equivalent example.
.Pp
See also
.Sx \&BI ,
.Sx \&BR ,
.Sx \&RB ,
.Sx \&RI ,
and
.Sx \&IR .
.Ss \&IP
Begin an indented paragraph with the following syntax:
.Bd -filled -offset indent
.Pf \. Sx \&IP
.Op Ar head Op Ar width
.Ed
.Pp
The
.Ar width
argument is a
.Xr roff 7
scaling width defining the left margin.
It's saved for later paragraph left-margins; if unspecified, the saved or
default width is used.
.Pp
The
.Ar head
argument is used as a leading term, flushed to the left margin.
This is useful for bulleted paragraphs and so on.
.Pp
See also
.Sx \&HP ,
.Sx \&LP ,
.Sx \&P ,
.Sx \&PP ,
and
.Sx \&TP .
.Ss \&IR
Text is rendered alternately in italics and roman (the default font).
Whitespace between arguments is omitted in output.
.Pp
See
.Sx \&BI
for an equivalent example.
.Pp
See also
.Sx \&BI ,
.Sx \&IB ,
.Sx \&BR ,
.Sx \&RB ,
and
.Sx \&RI .
.Ss \&LP
Begin an undecorated paragraph.
The scope of a paragraph is closed by a subsequent paragraph,
sub-section, section, or end of file.
The saved paragraph left-margin width is reset to the default.
.Pp
See also
.Sx \&HP ,
.Sx \&IP ,
.Sx \&P ,
.Sx \&PP ,
and
.Sx \&TP .
.Ss \&ME
End a mailto block.
This is a non-standard GNU extension, included only for compatibility.
See
.Sx \&MT .
.Ss \&MT
Begin a mailto block.
This is a non-standard GNU extension, included only for compatibility.
It has the following syntax:
.Bd -literal -offset indent
.Pf \. Sx \&MT Ar address
link description to be shown
.Pf \. Sx ME
.Ed
.Ss \&OP
Optional command-line argument.
This is a non-standard GNU extension, included only for compatibility.
It has the following syntax:
.Bd -filled -offset indent
.Pf \. Sx \&OP
.Ar key Op Ar value
.Ed
.Pp
The
.Ar key
is usually a command-line flag and
.Ar value
its argument.
.Ss \&P
Synonym for
.Sx \&LP .
.Pp
See also
.Sx \&HP ,
.Sx \&IP ,
.Sx \&LP ,
.Sx \&PP ,
and
.Sx \&TP .
.Ss \&PD
Specify the vertical space to be inserted before each new paragraph.
.br
The syntax is as follows:
.Bd -filled -offset indent
.Pf \. Sx \&PD
.Op Ar height
.Ed
.Pp
The
.Ar height
argument is a
.Xr roff 7
scaling width.
It defaults to
.Cm 1v .
If the unit is omitted,
.Cm v
is assumed.
.Pp
This macro affects the spacing before any subsequent instances of
.Sx \&HP ,
.Sx \&IP ,
.Sx \&LP ,
.Sx \&P ,
.Sx \&PP ,
.Sx \&SH ,
.Sx \&SS ,
and
.Sx \&TP .
.Ss \&PP
Synonym for
.Sx \&LP .
.Pp
See also
.Sx \&HP ,
.Sx \&IP ,
.Sx \&LP ,
.Sx \&P ,
and
.Sx \&TP .
.Ss \&R
Text is rendered in roman (the default font).
.Pp
See also
.Sx \&I
and
.Sx \&B .
.Ss \&RB
Text is rendered alternately in roman (the default font) and bold face.
Whitespace between arguments is omitted in output.
.Pp
See
.Sx \&BI
for an equivalent example.
.Pp
See also
.Sx \&BI ,
.Sx \&IB ,
.Sx \&BR ,
.Sx \&RI ,
and
.Sx \&IR .
.Ss \&RE
Explicitly close out the scope of a prior
.Sx \&RS .
The default left margin is restored to the state before that
.Sx \&RS
invocation.
.Pp
The syntax is as follows:
.Bd -filled -offset indent
.Pf \. Sx \&RE
.Op Ar level
.Ed
.Pp
Without an argument, the most recent
.Sx \&RS
block is closed out.
If
.Ar level
is 1, all open
.Sx \&RS
blocks are closed out.
Otherwise,
.Ar level No \(mi 1
nested
.Sx \&RS
blocks remain open.
.Ss \&RI
Text is rendered alternately in roman (the default font) and italics.
Whitespace between arguments is omitted in output.
.Pp
See
.Sx \&BI
for an equivalent example.
.Pp
See also
.Sx \&BI ,
.Sx \&IB ,
.Sx \&BR ,
.Sx \&RB ,
and
.Sx \&IR .
.Ss \&RS
Temporarily reset the default left margin.
This has the following syntax:
.Bd -filled -offset indent
.Pf \. Sx \&RS
.Op Ar width
.Ed
.Pp
The
.Ar width
argument is a
.Xr roff 7
scaling width.
If not specified, the saved or default width is used.
.Pp
See also
.Sx \&RE .
.Ss \&SB
Text is rendered in small size (one point smaller than the default font)
bold face.
.Ss \&SH
Begin a section.
The scope of a section is only closed by another section or the end of
file.
The paragraph left-margin width is reset to the default.
.Ss \&SM
Text is rendered in small size (one point smaller than the default
font).
.Ss \&SS
Begin a sub-section.
The scope of a sub-section is closed by a subsequent sub-section,
section, or end of file.
The paragraph left-margin width is reset to the default.
.Ss \&TH
Sets the title of the manual page for use in the page header
and footer with the following syntax:
.Bd -filled -offset indent
.Pf \. Sx \&TH
.Ar title section date
.Op Ar source Op Ar volume
.Ed
.Pp
Conventionally, the document
.Ar title
is given in all caps.
The recommended
.Ar date
format is
.Sy YYYY-MM-DD
as specified in the ISO-8601 standard;
if the argument does not conform, it is printed verbatim.
If the
.Ar date
is empty or not specified, the current date is used.
The optional
.Ar source
string specifies the organisation providing the utility.
When unspecified,
.Xr mandoc 1
uses its
.Fl Ios
argument.
The
.Ar volume
string replaces the default rendered volume, which is dictated by the
manual section.
.Pp
Examples:
.Pp
.Dl \&.TH CVS 5 "1992-02-12" GNU
.Ss \&TP
Begin a paragraph where the head, if exceeding the indentation width, is
followed by a newline; if not, the body follows on the same line after a
buffer to the indentation width.
Subsequent output lines are indented.
The syntax is as follows:
.Bd -filled -offset indent
.Pf \. Sx \&TP
.Op Ar width
.Ed
.Pp
The
.Ar width
argument is a
.Xr roff 7
scaling width.
If specified, it's saved for later paragraph left-margins; if
unspecified, the saved or default width is used.
.Pp
See also
.Sx \&HP ,
.Sx \&IP ,
.Sx \&LP ,
.Sx \&P ,
and
.Sx \&PP .
.Ss \&UC
Sets the volume for the footer for compatibility with man pages from
.Bx
releases.
The optional first argument specifies which release it is from.
.Ss \&UE
End a uniform resource identifier block.
This is a non-standard GNU extension, included only for compatibility.
See
.Sx \&UE .
.Ss \&UR
Begin a uniform resource identifier block.
This is a non-standard GNU extension, included only for compatibility.
It has the following syntax:
.Bd -literal -offset indent
.Pf \. Sx \&UR Ar uri
link description to be shown
.Pf \. Sx UE
.Ed
.Ss \&fi
End literal mode begun by
.Sx \&nf .
.Ss \&in
Indent relative to the current indentation:
.Pp
.D1 Pf \. Sx \&in Op Ar width
.Pp
If
.Ar width
is signed, the new offset is relative.
Otherwise, it is absolute.
This value is reset upon the next paragraph, section, or sub-section.
.Ss \&nf
Begin literal mode: all subsequent free-form lines have their end of
line boundaries preserved.
May be ended by
.Sx \&fi .
Literal mode is implicitly ended by
.Sx \&SH
or
.Sx \&SS .
.Sh MACRO SYNTAX
The
.Nm
macros are classified by scope: line scope or block scope.
Line macros are only scoped to the current line (and, in some
situations, the subsequent line).
Block macros are scoped to the current line and subsequent lines until
closed by another block macro.
.Ss Line Macros
Line macros are generally scoped to the current line, with the body
consisting of zero or more arguments.
If a macro is scoped to the next line and the line arguments are empty,
the next line, which must be text, is used instead.
Thus:
.Bd -literal -offset indent
\&.I
foo
.Ed
.Pp
is equivalent to
.Sq \&.I foo .
If next-line macros are invoked consecutively, only the last is used.
If a next-line macro is followed by a non-next-line macro, an error is
raised.
.Pp
The syntax is as follows:
.Bd -literal -offset indent
\&.YO \(lBbody...\(rB
\(lBbody...\(rB
.Ed
.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes
.It Sx \&AT Ta <=1 Ta current Ta \&
.It Sx \&B Ta n Ta next-line Ta \&
.It Sx \&BI Ta n Ta current Ta \&
.It Sx \&BR Ta n Ta current Ta \&
.It Sx \&DT Ta 0 Ta current Ta \&
.It Sx \&EE Ta 0 Ta current Ta compat
.It Sx \&EX Ta 0 Ta current Ta compat
.It Sx \&I Ta n Ta next-line Ta \&
.It Sx \&IB Ta n Ta current Ta \&
.It Sx \&IR Ta n Ta current Ta \&
.It Sx \&OP Ta 0, 1 Ta current Ta compat
.It Sx \&PD Ta 1 Ta current Ta \&
.It Sx \&R Ta n Ta next-line Ta \&
.It Sx \&RB Ta n Ta current Ta \&
.It Sx \&RI Ta n Ta current Ta \&
.It Sx \&SB Ta n Ta next-line Ta \&
.It Sx \&SM Ta n Ta next-line Ta \&
.It Sx \&TH Ta >1, <6 Ta current Ta \&
.It Sx \&UC Ta <=1 Ta current Ta \&
.It Sx \&fi Ta 0 Ta current Ta compat
.It Sx \&in Ta 1 Ta current Ta compat
.It Sx \&nf Ta 0 Ta current Ta compat
.El
.Pp
Macros marked as
.Qq compat
are included for compatibility with the significant corpus of existing
manuals that mix dialects of roff.
These macros should not be used for portable
.Nm
manuals.
.Ss Block Macros
Block macros comprise a head and body.
As with in-line macros, the head is scoped to the current line and, in
one circumstance, the next line (the next-line stipulations as in
.Sx Line Macros
apply here as well).
.Pp
The syntax is as follows:
.Bd -literal -offset indent
\&.YO \(lBhead...\(rB
\(lBhead...\(rB
\(lBbody...\(rB
.Ed
.Pp
The closure of body scope may be to the section, where a macro is closed
by
.Sx \&SH ;
sub-section, closed by a section or
.Sx \&SS ;
part, closed by a section, sub-section, or
.Sx \&RE ;
or paragraph, closed by a section, sub-section, part,
.Sx \&HP ,
.Sx \&IP ,
.Sx \&LP ,
.Sx \&P ,
.Sx \&PP ,
or
.Sx \&TP .
No closure refers to an explicit block closing macro.
.Pp
As a rule, block macros may not be nested; thus, calling a block macro
while another block macro scope is open, and the open scope is not
implicitly closed, is syntactically incorrect.
.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \&
.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \&
.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \&
.It Sx \&P Ta 0 Ta current Ta paragraph Ta \&
.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \&
.It Sx \&RE Ta 0 Ta current Ta none Ta compat
.It Sx \&RS Ta 1 Ta current Ta part Ta compat
.It Sx \&SH Ta >0 Ta next-line Ta section Ta \&
.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \&
.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \&
.It Sx \&UE Ta 0 Ta current Ta none Ta compat
.It Sx \&UR Ta 1 Ta current Ta part Ta compat
.El
.Pp
Macros marked
.Qq compat
are as mentioned in
.Sx Line Macros .
.Pp
If a block macro is next-line scoped, it may only be followed by in-line
macros for decorating text.
.Ss Font handling
In
.Nm
documents, both
.Sx Physical markup
macros and
.Xr roff 7
.Ql \ef
font escape sequences can be used to choose fonts.
In text lines, the effect of manual font selection by escape sequences
only lasts until the next macro invocation; in macro lines, it only lasts
until the end of the macro scope.
Note that macros like
.Sx \&BR
open and close a font scope for each argument.
.Sh SEE ALSO
.Xr man 1 ,
.Xr mandoc 1 ,
.Xr eqn 7 ,
.Xr mandoc_char 7 ,
.Xr mdoc 7 ,
.Xr roff 7 ,
.Xr tbl 7
.Sh HISTORY
The
.Nm
language first appeared as a macro package for the roff typesetting
system in
.At v7 .
It was later rewritten by James Clark as a macro package for groff.
Eric S. Raymond wrote the extended
.Nm
macros for groff in 2007.
The stand-alone implementation that is part of the
.Xr mandoc 1
utility written by Kristaps Dzonsons appeared in
.Ox 4.6 .
.Sh AUTHORS
This
.Nm
reference was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
.Sh CAVEATS
Do not use this language.
Use
.Xr mdoc 7 ,
instead.
mandoc-1.14.3/man.cgi.3 0100644 0002007 0000011 00000017525 13141336265 0014067 0 ustar 00schwarze wsrc .\" $Id: man.cgi.3,v 1.4 2017/03/15 13:18:53 schwarze Exp $
.\"
.\" Copyright (c) 2016, 2017 Ingo Schwarze
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: March 15 2017 $
.Dt MAN.CGI 3
.Os
.Sh NAME
.Nm man.cgi
.Nd internals of the CGI program to search and display manual pages
.Sh DESCRIPTION
The source code of
.Xr man.cgi 8
is organized in four levels:
.Pp
.Bl -enum -compact
.It
.Sx Top level
.It
.Sx Page generators
.It
.Sx Result generators
.It
.Sx Utility routines
.El
.Ss Top level
The top level of
.Xr man.cgi 8
consists of the
.Fn main
program and a few parser routines.
.Bl -tag -width 1n
.It Ft int Fn main void
The main program
.Bl -dash -compact
.It
limits execution time;
.It
changes to
.Dv MAN_DIR ,
the data directory containing all the manual trees;
.It
calls
.Fn parse_manpath_conf ;
.It
if
.Ev PATH_INFO
is empty, calls
.Fn parse_query_string ;
otherwise,
calls
.Fn parse_path_info ;
.It
validates the manpath and the architecture;
.It
calls the appropriate one among the
.Sx Page generators .
.El
.It Ft void Fn parse_manpath_conf "struct req *req"
Parses and validates
.Pa manpath.conf
and fills
.Va req->p
and
.Va req->psz .
.It Ft void Fn parse_path_info "struct req *req" "const char *path"
Parses and validates
.Ev PATH_INFO ,
clears
.Va req->isquery ,
and fills
.Va req->q .
.It Ft void Fn parse_query_string "struct req *req" "const char *qs"
Parses and validates
.Ev QUERY_STRING ,
sets
.Va req->isquery ,
and fills
.Va req->q .
This function is the only user of the utility functions
.Fn http_decode
and
.Fn set_query_attr .
.El
.Ss Page generators
The purpose of each page generator is to print a complete HTML page,
starting with the HTTP headers and continuing to the page footer.
Before starting HTML output with
.Fn resp_begin_html ,
some page generators do some preparatory work, for example to decide
which page to show.
Each page generator ends with a call to
.Fn resp_end_html .
.Bl -tag -width 1n
.It Ft void Fn pg_show "struct req *req" "const char *fullpath"
This page generator is used when
.Ev PATH_INFO
contains the complete path to a manual page including manpath,
section directory, optional architecture subdirectory, manual name
and section number suffix.
It validates the manpath, changes into it, validate the filename,
and then calls
.Fn resp_begin_html ,
.Fn resp_searchform ,
.Fn resp_show ,
and
.Fn resp_end_html
in that order.
.It Ft void Fn pg_search "const struct req *req"
This page generator is used when
.Ev PATH_INFO
contains a search query in short format or when
.Ev PATH_INFO
is empty and a
.Ev QUERY_STRING
is provided.
If possible, requests using
.Ev QUERY_STRING
are redirected to URIs using
.Ev PATH_INFO
by calling
.Fn pg_redirect .
Otherwise, it changes into the manpath and calls
.Xr mansearch 3 .
Depending on the result, it calls either
.Fn pg_noresult
or
.Fn pg_searchres .
.It Ft void Fn pg_redirect "const struct req *req" "const char *name"
This function is special in so far as it does not print an HTML page,
but only an HTTP 303 response with a Location: of the form:
.Sm off
.No http://
.Ar host Ns /
.Op Ar scriptname Ns /
.Op Ar manpath Ns /
.Op Ar arch Ns /
.Fa name
.Op Pf . Ar sec
.Sm on
.It Ft void Fn pg_noresult "const struct req *req" "const char *msg"
This function calls
.Fn resp_begin_html ,
.Fn resp_searchform ,
prints the
.Fa msg
passed to it, and calls
.Fn resp_end_html .
.It Ft void Fn pg_searchres "const struct req *req" "struct manpage *r"\
"size_t sz"
This function first validates the filenames found.
If
.Ev QUERY_STRING
was used and there is exactly one result,
it writes an HTTP redirect to that result.
Otherwise, it writes an HTML result page beginning with
.Fn resp_begin_html
and
.Fn resp_searchform .
If there is more than one result, it writes a list of links
to all the results.
If it was a
.Xr man 1
rather than an
.Xr apropos 1
query or if there is only one single result, it calls
.Fn resp_show .
Finally, it calls
.Fn resp_end_html .
.It Ft void Fn pg_index "const struct req *req"
This page generator is used when
.Ev PATH_INFO
and
.Ev QUERY_STRING
are both empty.
It calls
.Fn resp_begin_html
and
.Fn resp_searchform ,
writes links to help pages, and calls
.Fn resp_end_html .
.It Ft void Fn pg_error_badrequest "const char *msg"
This page generator is used when
.Fn main
or
.Fn pg_show
detect an invalid URI.
It calls
.Fn resp_begin_html ,
prints the
.Fa msg
provided, and calls
.Fn resp_end_html .
.It Ft void Fn pg_error_internal void
This page generator is used by various functions when errors are
detected in the
.Pa manpath.conf
configuration file, in
.Xr mandoc.db 5
databases, in the
.Xr mandoc 3
parser, in file system permissions, or when setting up timeouts.
It calls
.Fn resp_begin_html ,
prints
.Qq "Internal Server Error" ,
and calls
.Fn resp_end_html .
Before calling
.Fn pg_error_internal ,
call
.Xr warn 3
or
.Xr warnx 3
to log the reason of the error to the
.Xr httpd 8
server log file.
.El
.Ss Result generators
The purpose of result generators is to print a chunk of HTML code.
When they print untrusted strings or characters,
.Fn html_print
and
.Fn html_putchar
are used.
The highest level result generators are:
.Bl -tag -width 1n
.It Ft void Fn resp_begin_html "int code" "const char *msg" "const char *file"
This generator calls
.Fn resp_begin_http
to print the HTTP headers, then prints the HTML header up to the
opening tag of the element, then copies the file
.Pa header.html
to the output, if it exists and is readable.
If
.Fa file
is not
.Dv NULL ,
it is used for the element.
.It Ft void Fn resp_searchform "const struct req *req" "enum focus focus"
This generator prints a search form, filling it with data
from the provided request object.
If the
.Fa focus
argument is
.Dv FOCUS_QUERY ,
it sets the document's autofocus to the query input box.
.It Ft void Fn resp_show "const struct req *req" "const char *file"
This wrapper dispatches to either
.Fn resp_catman
or
.Fn resp_format ,
depending on whether
.Ar file
starts with
.Pa cat
or
.Pa man ,
respectively.
.It Ft void Fn resp_catman "const struct req *req" "const char *file"
This generator translates a preformatted, backspace-encoded manual
page to HTML and prints it to the output.
.It Ft void Fn resp_format "const struct req *req" "const char *file"
This generator formats a manual page on the standard output,
using the functions documented in
.Xr mchars_alloc 3
and
.Xr mandoc 3 .
.It Ft void Fn resp_end_html void
This generator copies the file
.Pa footer.html
to the output, if it exists and is readable,
and closes the <body> and <html> elements.
.El
.Ss Utility routines
These functions take a string and return 1 if it is valid, or 0 otherwise.
.Bl -tag -width 1n
.It Ft int Fn validate_urifrag "const char *frag"
Checks that the string only contains alphanumeric ASCII characters,
dashes, dots, slashes, and underscores.
.It Ft int Fn validate_manpath "const struct req *req" "const char* manpath"
Checks that the string is either
.Qq mandoc
or one of the manpaths configured in
.Pa manpath.conf .
.It Ft int Fn validate_filename "const char *file"
Checks that the string starts with
.Qq man
or
.Qq cat
and does not ascend to parent directories.
.El
.Sh SEE ALSO
.Xr mandoc 3 ,
.Xr mansearch 3 ,
.Xr mchars_alloc 3 ,
.Xr mandoc.db 5 ,
.Xr man.cgi 8
mandoc-1.14.3/man.cgi.8 0100644 0002007 0000011 00000025670 13141336265 0014074 0 ustar 00schwarze wsrc .\" $Id: man.cgi.8,v 1.22 2017/03/18 16:48:24 schwarze Exp $
.\"
.\" Copyright (c) 2014, 2015, 2016 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: March 18 2017 $
.Dt MAN.CGI 8
.Os
.Sh NAME
.Nm man.cgi
.Nd CGI program to search and display manual pages
.Sh DESCRIPTION
The
.Nm
CGI program searches for manual pages on a WWW server
and displays them to HTTP clients,
providing functionality equivalent to the
.Xr man 1
and
.Xr apropos 1
utilities.
It can use multiple manual trees in parallel.
.Ss HTML search interface
At the top of each generated HTML page,
.Nm
displays a search form containing these elements:
.Bl -enum
.It
An input box for search queries, expecting
either a name of a manual page or an
.Ar expression
using the syntax described in the
.Xr apropos 1
manual; filling this in is required for each search.
.Pp
The expression is broken into words at whitespace.
Whitespace characters and backslashes can be escaped
by prepending a backslash.
The effect of prepending a backslash to another character is undefined;
in the current implementation, it has no effect.
.It
A
.Xr man 1
submit button.
The string in the input box is interpreted as the name of a manual page.
.It
An
.Xr apropos 1
submit button.
The string in the input box is interpreted as a search
.Ar expression .
.It
A dropdown menu to optionally select a manual section.
If one is provided, it has the same effect as the
.Xr man 1
and
.Xr apropos 1
.Fl s
option.
Otherwise, pages from all sections are shown.
.It
A dropdown menu to optionally select an architecture.
If one is provided, it has the same effect as the
.Xr man 1
and
.Xr apropos 1
.Fl S
option.
By default, pages for all architectures are shown.
.It
A dropdown menu to select a manual tree.
If the configuration file
.Pa /var/www/man/manpath.conf
contains only one manpath, the dropdown menu is not shown.
By default, the first manpath given in the file is used.
.El
.Ss Program output
The
.Nm
program generates five kinds of output pages:
.Bl -tag -width Ds
.It The index page.
This is returned when calling
.Nm
without
.Ev PATH_INFO
and without a
.Ev QUERY_STRING .
It serves as a starting point for using the program
and shows the search form only.
.It A list page.
Lists are returned when searches match more than one manual page.
The first column shows the names and section numbers of manuals
as clickable links.
The second column shows the one-line descriptions of the manuals.
.It A manual page.
This output format is used when a search matches exactly one
manual page, or when a link on a list page or an
.Ic \&Xr
link on another manual page is followed.
.It A no-result page.
This is shown when a search request returns no results -
eiher because it violates the query syntax, or because
the search does not match any manual pages.
.It \&An error page.
This cannot happen by merely clicking the
.Dq Search
button, but only by manually entering an invalid URI.
It does not show the search form, but only an error message
and a link back to the index page.
.El
.Ss Setup
For each manual tree, create one first-level subdirectory below
.Pa /var/www/man .
The name of one of these directories is called a
.Dq manpath
in the context of
.Nm .
Create a single ASCII text file
.Pa /var/www/man/manpath.conf
containing the names of these directories, one per line.
The directory given first is used as the default manpath.
.Pp
Inside each of these directories, use the same directory and file
structure as found below
.Pa /usr/share/man ,
that is, second-level subdirectories
.Pa /var/www/man/*/man1 , /var/www/man/*/man2
etc. containing source
.Xr mdoc 7
and
.Xr man 7
manuals with file name extensions matching the section numbers,
second-level subdirectories
.Pa /var/www/man/*/cat1 , /var/www/man/*/cat2
etc. containing preformatted manuals with the file name extension
.Sq 0 ,
and optional third-level subdirectories for architectures.
Use
.Xr makewhatis 8
to create a
.Xr mandoc.db 5
database inside each manpath.
.Pp
Configure your web server to execute CGI programs located in
.Pa /cgi-bin .
When using
.Ox
.Xr httpd 8 ,
the
.Xr slowcgi 8
proxy daemon is needed to translate FastCGI requests to plain old CGI.
.Pp
To compile
.Nm ,
first copy
.Pa cgi.h.example
to
.Pa cgi.h
and edit it according to your needs.
It contains the following compile-time definitions:
.Bl -tag -width Ds
.It Ev COMPAT_OLDURI
Only useful for running on www.openbsd.org to deal with old URIs containing
.Qq "manpath=OpenBSD "
where the blank character has to be translated to a hyphen.
When compiling for other sites, this definition can be deleted.
.It Dv CSS_DIR
An optional file system path to the directory containing the file
.Pa mandoc.css ,
to be specified relative to the server's document root,
and to be specified without a trailing slash.
When empty, the CSS file is assumed to be in the document root.
Otherwise, a leading slash is needed.
This is used in generated HTML code.
.It Dv CUSTOMIZE_TITLE
An ASCII string to be used for the HTML <TITLE> element.
.It Dv MAN_DIR
A file system path to the
.Nm
data directory relative to the web server
.Xr chroot 2
directory, to be specified with a leading slash and without a trailing slash.
It needs to have at least one component; the root directory cannot be used
for this purpose.
The files
.Pa manpath.conf ,
.Pa header.html ,
and
.Pa footer.html
are looked up in this directory.
It is also prepended to the manpath when opening
.Xr mandoc.db 5
and manual page files.
.It Dv SCRIPT_NAME
The initial component of URIs, to be specified without leading
and trailing slashes.
It can be empty.
.El
.Pp
After editing
.Pa cgi.h ,
run
.Pp
.Dl make man.cgi
.Pp
and copy the resulting binary to the proper location,
for example using the command:
.Pp
.Dl make installcgi
.Pp
In addition to that, make sure the default manpath contains the files
.Pa man1/apropos.1
and
.Pa man8/man.cgi.8 ,
or the documentation links at the bottom of the index page will not work.
.Ss URI interface
.Nm
uniform resource identifiers are not needed for interactive use,
but can be useful for deep linking.
They consist of:
.Bl -enum
.It
The
.Cm http://
protocol specifier.
.It
The host name.
.It
The
.Dv SCRIPT_NAME ,
preceded by a slash unless empty.
.It
To show a single page, a slash, the manpath, another slash,
and the name of the requested file, for example
.Pa /OpenBSD-current/man1/mandoc.1 .
This can be abbreviated according to the following syntax:
.Sm off
.Op / Ar manpath
.Op / Cm man Ar sec
.Op / Ar arch
.Pf / Ar name Op \&. Ar sec
.Sm on
.It
For searches, a query string starting with a question mark
and consisting of
.Ar key Ns = Ns Ar value
pairs, separated by ampersands, for example
.Pa ?manpath=OpenBSD-current&query=mandoc .
Supported keys are
.Cm manpath ,
.Cm query ,
.Cm sec ,
.Cm arch ,
corresponding to
.Xr apropos 1
.Fl M ,
.Ar expression ,
.Fl s ,
.Fl S ,
respectively, and
.Cm apropos ,
which is a boolean parameter to select or deselect the
.Xr apropos 1
query mode.
For backward compatibility with the traditional
.Nm ,
.Cm sektion
is supported as an alias for
.Cm sec .
.El
.Ss Restricted character set
For security reasons, in particular to prevent cross site scripting
attacks, some strings used by
.Nm
can only contain the following characters:
.Pp
.Bl -dash -compact -offset indent
.It
lower case and upper case ASCII letters
.It
the ten decimal digits
.It
the dash
.Pq Sq -
.It
the dot
.Pq Sq \&.
.It
the slash
.Pq Sq /
.It
the underscore
.Pq Sq _
.El
.Pp
In particular, this applies to all manpaths and architecture names.
.Sh ENVIRONMENT
The web server may pass the following CGI variables to
.Nm :
.Bl -tag -width Ds
.It Ev SCRIPT_NAME
The initial part of the URI passed from the client to the server,
starting after the server's host name and ending before
.Ev PATH_INFO .
This is ignored by
.Nm .
When constructing URIs for links and redirections, the
.Dv SCRIPT_NAME
preprocessor constant is used instead.
.It Ev PATH_INFO
The final part of the URI path passed from the client to the server,
starting after the
.Ev SCRIPT_NAME
and ending before the
.Ev QUERY_STRING .
It is used by the
.Cm show
page to acquire the manpath and filename it needs.
.It Ev QUERY_STRING
The HTTP query string passed from the client to the server.
It is the final part of the URI, after the question mark.
It is used by the
.Cm search
page to acquire the named parameters it needs.
.El
.Sh FILES
.Bl -tag -width Ds
.It Pa /var/www
Default web server
.Xr chroot 2
directory.
All the following paths are specified relative to this directory.
.It Pa /cgi-bin/man.cgi
The usual file system path to the
.Nm
program inside the web server
.Xr chroot 2
directory.
A different name can be chosen, but in any case, it needs to be configured in
.Xr httpd.conf 5 .
.It Pa /htdocs
The file system path to the server document root directory
relative to the server
.Xr chroot 2
directory.
This is part of the web server configuration and not specific to
.Nm .
.It Pa /htdocs/mandoc.css
A style sheet for
.Xr mandoc 1
HTML styling, referenced from each generated HTML page.
.It Pa /man
Default
.Nm
data directory containing all the manual trees.
Can be overridden by
.Dv MAN_DIR .
.It Pa /man/manpath.conf
The list of available manpaths, one per line.
If any of the lines in this file contains a slash
.Pq Sq /
or any character not contained in the
.Sx Restricted character set ,
.Nm
reports an internal server error and exits without doing anything.
.It Pa /man/header.html
An optional file containing static HTML code to be inserted right
after opening the <BODY> element.
.It Pa /man/footer.html
An optional file containing static HTML code to be inserted right
before closing the <BODY> element.
.It Pa /man/OpenBSD-current/man1/mandoc.1
An example
.Xr mdoc 7
source file located below the
.Dq OpenBSD-current
manpath.
.El
.Sh COMPATIBILITY
The
.Nm
CGI program is call-compatible with queries from the traditional
.Pa man.cgi
script by Wolfram Schneider.
However, the output may not be quite the same.
.Sh SEE ALSO
.Xr apropos 1 ,
.Xr mandoc.db 5 ,
.Xr makewhatis 8 ,
.Xr slowcgi 8
.Sh HISTORY
A version of
.Nm
based on
.Xr mandoc 1
first appeared in mdocml-1.12.1 (March 2012).
The current
.Xr mandoc.db 5
database format first appeared in
.Ox 6.1 .
.Sh AUTHORS
.An -nosplit
The
.Nm
program was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
and is maintained by
.An Ingo Schwarze Aq Mt schwarze@openbsd.org ,
who also designed and implemented the database format.
mandoc-1.14.3/man.conf.5 0100644 0002007 0000011 00000007337 13141336265 0014254 0 ustar 00schwarze wsrc .\" $Id: man.conf.5,v 1.4 2016/12/28 22:52:17 schwarze Exp $
.\"
.\" Copyright (c) 2015 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: December 28 2016 $
.Dt MAN.CONF 5
.Os
.Sh NAME
.Nm man.conf
.Nd configuration file for man
.Sh DESCRIPTION
This is the configuration file
for the
.Xr man 1 ,
.Xr apropos 1 ,
and
.Xr makewhatis 8
utilities.
Its presence, and all directives, are optional.
.Pp
This file is an ASCII text file.
Leading whitespace on lines, lines starting with
.Sq # ,
and blank lines are ignored.
Words are separated by whitespace.
The first word on each line is the name of a configuration directive.
.Pp
The following directives are supported:
.Bl -tag -width Ds
.It Ic manpath Ar path
Override the default search
.Ar path
for
.Xr man 1 ,
.Xr apropos 1 ,
and
.Xr makewhatis 8 .
It can be used multiple times to specify multiple paths,
with the order determining the manual page search order.
.Pp
Each path is a tree containing subdirectories
whose names consist of the strings
.Sq man
and/or
.Sq cat
followed by the names of sections, usually single digits.
The former are supposed to contain unformatted manual pages in
.Xr mdoc 7
and/or
.Xr man 7
format; file names should end with the name of the section
preceded by a dot.
The latter should contain preformatted manual pages;
file names should end with
.Ql .0 .
.Pp
Creating a
.Xr mandoc.db 5
database with
.Xr makewhatis 8
in each directory configured with
.Ic manpath
is recommended and necessary for
.Xr apropos 1
to work, but not strictly required for
.Xr man 1 .
.It Ic output Ar option Op Ar value
Configure the default value of an output option.
These directives are overridden by the
.Fl O
command line options of the same names.
For details, see the
.Xr mandoc 1
manual.
.Pp
.Bl -column fragment integer "ascii, utf8" -compact
.It Ar option Ta Ar value Ta used by Fl T Ta purpose
.It Ta Ta Ta
.It Ic fragment Ta none Ta Cm html Ta print only body
.It Ic includes Ta string Ta Cm html Ta path to header files
.It Ic indent Ta integer Ta Cm ascii , utf8 Ta left margin
.It Ic man Ta string Ta Cm html Ta path for \&Xr links
.It Ic paper Ta string Ta Cm ps , pdf Ta paper size
.It Ic style Ta string Ta Cm html Ta CSS file
.It Ic width Ta integer Ta Cm ascii , utf8 Ta right margin
.El
.It Ic _whatdb Ar path Ns Cm /whatis.db
This directive provides the same functionality as
.Ic manpath ,
but using a historic and misleading syntax.
It is kept for backward compatibility for now,
but will eventually be removed.
.El
.Sh FILES
.Pa /etc/man.conf
.Sh EXAMPLES
The following configuration file reproduces the defaults:
installing it is equivalent to not having a
.Nm
file at all.
.Bd -literal -offset indent
manpath /usr/share/man
manpath /usr/X11R6/man
manpath /usr/local/man
.Ed
.Sh SEE ALSO
.Xr apropos 1 ,
.Xr man 1 ,
.Xr makewhatis 8
.Sh HISTORY
A relatively complicated
.Nm
file format first appeared in
.Bx 4.3 Reno .
For
.Ox 5.8 ,
it was redesigned from scratch, aiming for simplicity.
.Sh AUTHORS
.An Ingo Schwarze Aq Mt schwarze@openbsd.org
mandoc-1.14.3/man.h 0100644 0002007 0000011 00000002031 13141336265 0013375 0 ustar 00schwarze wsrc /* $Id: man.h,v 1.78 2017/04/24 23:06:18 schwarze Exp $ */
/*
* Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
* Copyright (c) 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
struct roff_man;
const struct mparse *man_mparse(const struct roff_man *);
void man_validate(struct roff_man *);
mandoc-1.14.3/man.options.1 0100644 0002007 0000011 00000052062 13141336265 0015011 0 ustar 00schwarze wsrc .\" $Id: man.options.1,v 1.7 2017/07/04 23:40:01 schwarze Exp $
.\"
.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: July 4 2017 $
.Dt MAN.OPTIONS 1
.Os
.Sh NAME
.Nm man.options
.Nd assignment of option letters in manual page utilities
.\"
.\" Sources that occur repeatedly.
.\" Only use if the precise implementation time is unknown.
.\"
.de PWB
.No PWB/UNIX 1.0 Pq July 1, 1977 \\$1
..
.de At7
.At v7 Pq January 1979 \\$1
..
.de At3
.At III Pq June 1980 \\$1
..
.de Bx4
.Bx 4 Pq November 16, 1980 \\$1
..
.de At5
.At V Pq January 1983 \\$1
..
.de Bx43
.Bx 4.3 Pq June 1986 \\$1
..
.\" option was present in groff-1.01 as contained in 4.3BSD-Net/2
.\" and no mention of it could be found in the ChangeLog,
.\" so it's probably older than groff-0.4, where the log started
.de g04
.No probably before groff-0.4 Pq before July 14, 1990 \\$1
..
.de Eaton
.No Eaton Pq before July 7, 1993; 1990/91? \\$1
..
.\" man-1.5e was released on July 11, 1998.
.de man15e
.No man-1.5e Pq not before 1993, not after 1998 \\$1
..
.\" man-1.5g was released on April 7, 1999.
.de man15g
.No man-1.5g Pq not before 1993, not after 1999 \\$1
..
.\" code first seen in the initial import of man-db into CVS ,
.\" which was more or less debian man-db-2.3.17
.\" Colin Watson's first release was 2.3.18 on May 14, 2001
.\" no clue about it found in ChangeLog-2013,
.\" so it was probably already present before man-db-2.2a4
.de dbI
.No man-db probably before 2.2a4 Pq before Nov 8, 1994 \\$1
..
.\"
.\" --------------------------------------------------------------------
.\"
.Sh DESCRIPTION
This manual page lists option letters used in many different versions
of the
.Nm man ,
.Nm apropos ,
.Nm whatis ,
.Nm mandoc ,
.Nm makewhatis ,
.Nm mandb ,
.Nm makemandb ,
.Nm catman ,
and
.Nm manpath
utilities.
Option letters used by
.Nm groff ,
.Nm nroff ,
.Nm troff ,
and
.Nm roff
are also included because beginning with
.At v7 ,
many versions of
.Xr man 1
pass on unrecognized options to these programs.
.Pp
For each option letter, information is first grouped into paragraphs,
each paragraph describing similar functionality and starting with
one line briefly summarizing that functionality.
.Pp
For each program using the letter for that functionality, one line
is provided, giving the name of the program, a colon, the system
where this letter first appeared for this functionality in this
program, optionally a comma and a list of other system versions
introducing the same, a semicolon, and a list of current systems
supporting it.
If a system appears before the semicolon, it is not repeated
afterwards.
.Pp
Entries are sorted by historical precedence, except that obsolete
options are moved to the end.
Dates are commit dates where known, and release dates otherwise.
.Bl -tag -width 3n
.It Fl a
display all matching manual pages
.br
.Nm man :
.Bx 4.3 Tahoe Pq June 1988 ,
.Eaton ;
.Ox , Fx , Nx , No man-db , man-1.6 , illumos , Solaris 9-11
.br
.Nm apropos , whatis , mandoc :
.Ox 5.7 Pq August 27, 2014
.Pp
only display items that match all keywords
.br
.Nm apropos :
.No man-db Pq Aug 29, 2007
.Pp
use all directories and files for
.Xr mandoc.db 5
.br
.Nm makewhatis :
.Ox 5.6 Pq April 18, 2014
.Pp
.Bq superseded by Fl T Cm ascii
ASCII output mode
.br
.Nm troff :
.At7
.br
.Nm groff :
.g04
.It Fl B
use specified browser
.br
.Nm man :
.No man-1.6 Pq June 24, 2005
.It Fl b
print a backtrace with each warning or error message
.br
.Nm groff :
.g04
.Pp
.Bq obsolete hardware
report whether the phototypesetter is busy
.br
.Nm troff :
.At7
.It Fl C
alternate configuration file
.br
.Nm apropos , whatis :
.Bx 4.4 Lite1 Pq April 22, 1994 ,
.No man-db Pq Feb 22, 2003 ;
.Ox , Nx
.br
.Nm man :
.Nx 1.0 Pq Oct 26, 1994 ,
.man15e ;
.Ox
.br
.Nm mandb , catman , manpath :
.No man-db Pq Feb 22, 2003
.br
.Nm makemandb :
.Nx Pq Feb 7, 2012
.br
.Nm makewhatis :
.Ox 5.6 Pq April 18, 2014
.br
.Nm mandoc :
.Ox 5.7 Pq August 27, 2014
.Pp
.Bq obsolete
enable compatibility mode
.br
.Nm groff :
.No before groff-0.5 Pq before August 3, 1990
.It Fl c
do not use a pager
.br
.Nm man :
.Bx 4.3 Reno Pq June 1990 ;
.Ox , Nx
.br
.Nm apropos , whatis , mandoc :
.Ox 5.7 Pq August 27, 2014
.Pp
process given catpath
.br
.Nm makewhatis :
.Pq not before 1992, not after 1995
.Pp
recreate databases from scratch
.br
.Nm mandb :
.dbI
.Pp
produce a catpath as opposed to a manpath
.br
.Nm manpath :
.dbI
.Pp
internal option for use by
.Xr catman 1
.br
.Nm man :
.dbI
.Pp
reformat source page even if cat page exists
.br
.Nm man :
.man15e
.Pp
disable terminal color output in
.Xr grotty 1
.br
.Nm groff :
.No groff-1.18.0 Pq Oct 4, 2001
.Pp
recreate nroff versions from SGML sources
.br
.Nm catman :
.No Solaris 9-11
.Pp
.Bq obsolete
postprocess with
.Xr col 1
.br
.Nm man :
.At3 ,
.At5
.It Fl D
reset whatever was set with
.Ev MANOPT
.br
.Nm man :
.dbI
.Pp
print debugging info in addition to manual page
.br
.Nm man :
.man15e
.Pp
set default input encoding for
.Xr preconv 1
.br
.Nm groff :
.No groff-1.20 Pq August 20, 2008
.Pp
display all files added to
.Xr mandoc.db 5
.br
.Nm makewhatis :
.Ox 5.6 Pq April 18, 2014
.It Fl d
define a user-defined string
.br
.Nm groff :
.g04
.Pp
print debugging information
.br
.Nm man :
.Eaton ;
.Fx , No man-db , man-1.6 , illumos , Solaris 9-11
.br
.Nm manpath :
.Eaton ;
.Fx , No man-db
.br
.Nm apropos , whatis :
.dbI ;
.Fx
.br
.Nm mandb , catman :
.dbI
.Pp
remove and re-add a file to
.Xr mandoc.db 5
.br
.Nm makewhatis :
.Ox 2.7 Pq Feb 3, 2000
.Pp
.Bq superseded by Fl l
interpret arguments as file names
.br
.Nm man :
.At3 ,
.At5
.It Fl E
inhibit all error messages
.br
.Nm groff :
.g04
.Pp
select output encoding
.br
.Nm man :
.No man-db Pq Dec 23, 2001
.It Fl e
preprocess with
.Xr eqn 7
.br
.Nm man :
.At7
.br
.Nm groff :
.g04
.Pp
adjust text to left and right margins
.br
.Nm nroff :
.At7
.Pp
use exact matching
.br
.Nm apropos , whatis :
.dbI
.Pp
restrict search by section extension
.br
.Nm man :
.No man-db-2.3.5 Pq April 21, 1995
.It Fl F
use alternate font directory
.br
.Nm troff :
.Bx 4.2 Pq September 1983
.br
.Nm groff :
.g04
.Pp
preformat only, do not display
.br
.Nm man :
.No man-1.5g Pq April 7, 1999
.Pp
force searching dirs, do not use index (default)
.br
.Nm man :
.No illumos , Solaris 9-11
.It Fl f
.Xr whatis 1
mode
.br
.Nm man :
.Bx4 ,
.Eaton ;
.Ox , Fx , No man-db , man-1.6
.br
.Nm apropos , whatis :
.No man-db Pq Dec 2, 2010 ,
.Ox 5.7 Pq August 27, 2014
.br
.Nm mandoc :
.Ox 5.7 Pq August 27, 2014
.Pp
set the default font family
.br
.Nm groff :
.g04
.Pp
force formatting even if cat page is newer
.br
.Nm catman :
.Fx Pq March 15, 1995
.Pp
update only the entries for the given file
.br
.Nm mandb :
.No man-db Pq Feb 21, 2003
.Pp
force rebuilding the database from scratch
.br
.Nm makemandb :
.Nx Pq Feb 7, 2012
.Pp
locate manual page related to given file name
.br
.Nm man :
.No illumos , Solaris 9-11
.Pp
.Bq obsolete hardware
do not feed out paper nor stop phototypesetter
.br
.Nm troff :
.At7
.It Fl G
preprocess with
.Xr grap 1
.br
.Nm groff :
.No groff-1.16 Pq May 1, 2000
.It Fl g
produce a global manpath
.br
.Nm manpath :
.No man-db-2.2a7 Pq Nov 16, 1994
.Pp
preprocess with
.Xr grn 1
.br
.Nm groff :
.No groff-1.16 Pq Feb 20, 2000
.Pp
.Bq obsolete hardware
output to a GCOS phototypesetter
.br
.Nm troff :
.At7
.Pp
.Bq obsolete hardware
output to a DASI 300 terminal in 12-pitch mode
.br
.Nm man :
.PWB
.It Fl H
read hyphenation patterns from the given file
.br
.Nm groff :
.g04
.Pp
produce HTML output
.br
.Nm man :
.No man-db-1.3.12 to 1.3.17 Pq not before 1996, not after 2001
.Pp
use program to render HTML files as text
.br
.Nm man :
.No man-1.6 Pq June 24, 2005
.It Fl h
print a help message and exit
.br
.Nm groff :
.g04
.br
.Nm man :
.Eaton ;
.Fx , No man-db , man-1.6
.br
.Nm manpath :
.Eaton ;
.Fx , No man-db
.br
.Nm apropos , whatis , mandb , catman :
.dbI
.Pp
display the SYNOPSIS lines only
.br
.Nm man :
.Bx 4.3 Net/2 Pq August 20, 1991 ;
.Ox , Nx
.br
.Nm apropos , whatis , mandoc :
.Ox 5.7 Pq Sep 3, 2014
.Pp
turn on HTML formatting
.br
.Nm apropos :
.Nx Pq Apr 2, 2013
.Pp
.Bq obsolete
replace spaces by tabs in the output
.br
.Nm roff , nroff :
.At7
.It Fl I
input file search path for
.Xr soelim 1
.br
.Nm groff :
.No groff-1.12 Pq Sep 11, 1999
.Pp
respect case when matching manual page names
.br
.Nm man , catman :
.No man-db Pq Apr 21, 2002
.Pp
input options, in particular default operating system name
.br
.Nm mandoc :
.Ox 5.2 Pq May 24, 2012
.br
.Nm man , apropos , whatis :
.Ox 5.7 Pq August 27, 2014
.It Fl i
read standard input after the input files are exhausted
.br
.Nm nroff , troff :
.At7
.br
.Nm groff :
.g04
.Pp
ignore case when matching manual page names
.br
.Nm man , catman :
.No man-db Pq Apr 21, 2002
.Pp
turn on terminal escape code formatting
.br
.Nm apropos :
.Nx Pq March 29, 2013
.It Fl J
preprocess with
.Xr gideal 1
.br
.Nm groff :
.No groff-1.22.3 Pq June 17, 2014
.It Fl j
preprocess with
.Xr chem 1
.br
.Nm groff :
.No groff-1.22 Pq Jan 22, 2011
.It Fl K
source code full text search
.br
.Nm man :
.man15e ,
.No man-db Pq June 28, 2009 ;
.No Solaris 11
.Pp
input encoding
.br
.Nm groff :
.No groff-1.20 Pq Dec 31, 2005
.br
.Nm man , apropos , whatis , mandoc :
.Ox 5.7 Pq Oct 30, 2014
.It Fl k
.Xr apropos 1
mode
.br
.Nm man :
.Bx4 ,
.Eaton ;
.No POSIX , Ox , Fx , Nx , No man-db , man-1.6 , illumos , Solaris 9-11
.br
.Nm apropos , whatis , mandoc :
.Ox 5.7 Pq August 27, 2014
.Pp
ignore formatting errors
.br
.Nm catman :
.Nx Pq April 26, 1994
.Pp
preprocess with
.Xr preconv 1
.br
.Nm groff :
.No groff-1.20 Pq Dec 31, 2005
.Pp
.Bq obsolete hardware
display on a Tektronix 4014 terminal
.br
.Nm man :
.At7
.It Fl L
pass argument to the spooler
.br
.Nm groff :
.No groff-0.6 Pq Sep 14, 1990
.Pp
use alternate
.Xr locale 1
.br
.Nm man , apropos , whatis :
.No before man-db-2.2a13 Pq before Dec 15, 1994
.Pp
print list of locales
.br
.Nm manpath :
.Fx Pq Nov 23, 1999
.Pp
use
.Xr locale 1
specified in the environment
.br
.Nm catman :
.Fx Pq May 18, 2002
.It Fl l
spool the output
.br
.Nm groff :
.g04
.Pp
interpret arguments as file names
.br
.Nm man :
.No before man-2.2a7 Pq before Nov 16, 1994 ,
.Ox 5.7 Pq Aug 30, 2014
.br
.Nm apropos , whatis , mandoc :
.Ox 5.7 Pq Aug 30, 2014
.Pp
do not trim output to the terminal width
.br
.Nm apropos , whatis :
.No man-db Pq Aug 19, 2007
.Pp
only parse NAME sections
.br
.Nm makemandb :
.Nx Pq Feb 7, 2012
.Pp
legacy mode: search Nm,Nd, no context or formatting
.br
.Nm apropos :
.Nx Pq March 29, 2013
.Pp
list all manual pages matching name within the search path
.br
.Nm man :
.No illumos , Solaris 9-11
.It Fl M
override manual page search path
.br
.Nm man :
.Bx43 ,
.Eaton ;
.Ox , Fx , Nx , No man-db , man-1.6 , illumos , Solaris 9-11
.br
.Nm apropos , whatis :
.Bx43 ,
.No before man-db-2.2a14 Pq before Dec 16, 1994 ;
.Ox , No illumos
.br
.Nm catman :
.dbI ;
.Nx Pq July 27, 1993 ,
.No Solaris 9-11
.br
.Nm mandoc :
.Ox 5.7 Pq August 27, 2014
.Pp
prepend to macro file search path
.br
.Nm groff :
.g04
.Pp
do not show the context of the match
.br
.Nm apropos :
.Nx Pq May 22, 2016
.It Fl m
specify input macro language
.br
.Nm nroff , troff :
.At7
.br
.Nm groff :
.g04
.br
.Nm mandoc :
.Ox 4.8 Pq April 6, 2009
.Pp
augment manual page search path
.br
.Nm man , apropos , whatis :
.Bx 4.3 Reno Pq June 1990 ;
.Ox , Nx
.br
.Nm catman :
.Nx Pq Apr 4, 1999
.br
.Nm mandoc :
.Ox 5.7 Pq August 27, 2014
.Pp
override operating system
.br
.Nm man :
.Eaton ;
.No man-db , man-1.6
.br
.Nm apropos , whatis , manpath :
.dbI
.Pp
override architecture
.br
.Nm man :
.Fx Pq Jan 11, 2002
.Pp
show the context of the match
.br
.Nm apropos :
.Nx Pq May 22, 2016
.It Fl N
do not allow newlines between
.Xr eqn 7
delimiters
.br
.Nm groff :
.No groff-1.01 Pq Feb 21, 1991
.It Fl n
specify a page number for the first page
.br
.Nm troff :
.At7
.br
.Nm groff :
.g04
.Pp
.Xr nroff 1
output mode
.br
.Nm man :
.At7
.Pp
do not create the
.Xr whatis 1
database
.br
.Nm catman :
.Nx Pq July 27, 1993
.Pp
print commands instead of executing them
.br
.Nm catman :
.Fx Pq May 18, 2002 ,
.No Solaris 9-11
.Pp
limit the number of results
.br
.Nm apropos :
.Nx Pq Feb 7, 2012
.Pp
dry run simulating
.Xr mandoc.db 5
creation
.br
.Nm makewhatis :
.Ox 5.6 Pq April 18, 2014
.It Fl O
output options
.br
.Nm mandoc :
.Ox 4.8 Pq Oct 27, 2009
.br
.Nm man , apropos , whatis :
.Ox 5.7 Pq August 27, 2014
.It Fl o
select pages by numbers
.br
.Nm nroff , troff :
.At7
.br
.Nm groff :
.g04
.Pp
force use of non-localized manual pages
.br
.Nm man :
.Fx Pq June 7, 1999
.Pp
optimize index for speed and disk space
.br
.Nm makemandb :
.Nx Pq Feb 7, 2012
.It Fl P
pass argument to postprocessor
.br
.Nm groff :
.No groff-0.6 Pq Sep 14, 1990
.Pp
use specified pager
.br
.Nm man :
.Eaton ;
.Fx , No man-db , man-1.6
.Pp
turn on pager formatting
.br
.Nm apropos :
.Nx Pq Apr 2, 2013
.It Fl p
preprocess with
.Xr pic 1
.br
.Nm groff :
.g04
.Pp
use the given list of preprocessors
.br
.Nm man :
.Eaton ;
.Fx , No man-db , man-1.6
.Pp
dry run, display commands instead of executing them
.br
.Nm catman :
.Nx Pq July 27, 1993 ,
.Fx Pq March 15, 1995 to May 18, 2002 ,
.No Solaris 9-11
.Pp
print warnings when building
.Xr mandoc.db 5
.br
.Nm makewhatis :
.Ox 2.7 Pq April 23, 2000
.Pp
do not look for deleted manual pages
.br
.Nm mandb :
.No man-db Pq June 28, 2001
.Pp
print the search path for manual pages
.br
.Nm man :
.Nx Pq June 14 , 2011
.Pp
turn on pager formatting and pipe through pager
.br
.Nm apropos :
.Nx Pq Feb 7, 2012
.Pp
.Bq obsolete hardware
set phototypesetter point size
.br
.Nm troff :
.At7
.It Fl Q
print only fatal error messages
.br
.Nm makemandb :
.Nx Pq Aug 29, 2012
.Pp
quick mode of
.Xr mandoc.db 5
creation
.br
.Nm makewhatis :
.Ox 5.6 Pq April 18, 2014
.It Fl q
invoke the simultaneous input-output mode of the .rd request
.br
.Nm nroff , troff :
.At7
.Pp
issue no warnings
.br
.Nm manpath :
.Eaton ;
.Fx , No man-db
.br
.Nm mandb :
.dbI
.Pp
print only warnings and errors, no status updates
.br
.Nm makemandb :
.Nx Pq Aug 29, 2012
.It Fl R
postprocess with
.Xr refer 1
.br
.Nm groff :
.No groff-1.02 Pq June 2, 1991
.Pp
recode to the specified encoding
.br
.Nm man :
.No man-db Pq Dec 31, 2007
.It Fl r
set number register
.br
.Nm nroff , troff :
.At7
.br
.Nm groff :
.g04
.Pp
scan for and remove junk files
.br
.Nm catman :
.Fx Pq March 31, 1995
.Pp
set
.Xr less 1
prompt
.br
.Nm man :
.No man-db-2.3.5 Pq April 21, 1995
.Pp
use regular expression matching
.br
.Nm apropos , whatis :
.No man-db-2.3.5 Pq April 21, 1995
.Pp
turn off formatting
.br
.Nm apropos :
.Nx Pq Feb 10, 2013
.Pp
check for formatting errors, do not display
.br
.Nm man :
.No illumos , Solaris 9-11
.It Fl S
manual section search list
.br
.Nm man :
.Eaton ;
.Fx , No man-db , man-1.6
.Pp
safer mode
.br
.Nm groff :
.No groff-1.10 Pq May 17, 1994
.Pp
restrict architecture
.br
.Nm man :
.Ox 2.3 Pq March 9, 1998 ,
.Nx Pq May 27, 2000
.br
.Nm apropos :
.Ox 4.5 Pq Dec 24, 2008 ,
.Nx Pq May 8, 2009
.br
.Nm whatis :
.Ox 5.6 Pq April 18, 2014
.br
.Nm mandoc :
.Ox 5.7 Pq August 27, 2014
.It Fl s
preprocess with
.Xr soelim 1
.br
.Nm groff :
.g04
.Pp
silent mode, do not echo commands
.br
.Nm catman :
.Nx Pq April 26, 1994
.Pp
restrict section
.br
.Nm makewhatis :
.man15g
.br
.Nm man :
.Ox 2.3 Pq March 9, 1998 ,
.Nx Pq June 12, 2000 ;
.No illumos , Solaris 9-11
.br
.Nm apropos :
.No man-db Pq Nov 16, 2003 ,
.Ox 4.5 Pq Dec 24, 2008 ,
.Nx Pq May 8, 2009 ;
.No illumos
.br
.Nm whatis :
.No man-db Pq Nov 16, 2003 ,
.Ox 5.6 Pq April 18, 2014 ;
.No illumos
.br
.Nm mandoc :
.Ox 5.7 Pq August 27, 2014
.Pp
do not look for stray cats
.br
.Nm mandb :
.dbI
.Pp
.Bq SysV compat, recommends Fl S
manual section search list
.br
.Nm man :
.No man-db Pq Jan 1, 2008
.Pp
.Bq superseded by Fl h
display the SYNOPSIS lines only
.br
.Nm man :
.PWB
.Pp
.Bq obsolete hardware
pause before each page for paper manipulation
.br
.Nm roff :
.At7
.Pp
.Bq obsolete hardware
.Xr troff 1
output mode, small format
.br
.Nm man :
.At3 ,
.At5
.It Fl T
select terminal output format
.br
.Nm nroff :
.At7
.br
.Nm man :
.At3 ,
.At5 ,
.dbI ,
.Ox 5.7 Pq August 27, 2014
.br
.Nm groff :
.g04
.br
.Nm mandoc :
.Ox 4.8 Pq April 6, 2009
.br
.Nm apropos , whatis :
.Ox 5.7 Pq August 27, 2014
.Pp
use UTF-8 for
.Xr mandoc.db 5
.br
.Nm makewhatis :
.Ox 5.6 Pq April 18, 2014
.Pp
.Bq superseded by Fl m
use other macro package
.br
.Nm man , catman :
.No Solaris 9-11
.It Fl t
.Xr troff 1
output mode
.br
.Nm man :
.PWB ,
.At7 ,
.Bx 2 Pq May 10, 1979 ,
.At3 ,
.At5 ,
.Eaton ;
.Fx , No man-db , man-1.6 , illumos , Solaris 9-11
.br
.Nm catman :
.No Solaris 9-11
.Pp
preprocess with
.Xr tbl 7
.br
.Nm groff :
.g04
.Pp
check manual pages in the hierarchy
.br
.Nm mandb :
.No man-db-1.3.12 to 1.3.17 Pq not before 1996, not after 2001
.Pp
check files for problems related to
.Xr mandoc.db 5
.br
.Nm makewhatis :
.Ox 2.7 Pq April 23, 2000
.It Fl U
unsafe mode
.br
.Nm groff :
.No groff-1.12 Pq Dec 13, 1999
.It Fl u
update database
.br
.Nm makewhatis :
.Pq not before 1992, not after 1995
.Pp
create user databases only
.br
.Nm mandb :
.dbI
.Pp
update database cache (requires suid)
.br
.Nm man :
.No before man-db-2.2a10 Pq before Dec 6, 1994
.Pp
remove files from
.Xr mandoc.db 5
.br
.Nm makewhatis :
.Ox 3.4 Pq July 9, 2003
.It Fl V
print the pipeline on stdout instead of executing it
.br
.Nm groff :
.No groff-0.6 Pq Sep 2, 1990
.Pp
print version information
.br
.Nm man , apropos , whatis , mandb , catman , manpath :
.dbI
.It Fl v
print version number
.br
.Nm groff :
.g04
.Pp
verbose mode
.br
.Nm catman :
.Fx Pq March 15, 1995
.br
.Nm makewhatis :
.man15g
.br
.Nm apropos , whatis :
.No man-db Pq Dec 29, 2002
.Pp
print the name of every parsed file
.br
.Nm makemandb :
.Nx Pq Feb 7, 2012
.Pp
.Bq obsolete hardware
produce output on the Versatec printer
.br
.Nm man :
.PWB
.It Fl W
disable the named warning
.br
.Nm groff :
.No groff-0.5 Pq August 14, 1990
.Pp
list pathnames without additional information
.br
.Nm man :
.man15e
.Pp
list pathnames of cat files
.br
.Nm man :
.No man-db Pq Aug 13, 2002
.Pp
minimum message level to display
.br
.Nm mandoc :
.Ox 4.8 Pq April 6, 2009
.br
.Nm man , apropos , whatis :
.Ox 5.7 Pq August 27, 2014
.It Fl w
list pathnames
.br
.Nm man :
.At7 ,
.At3 ,
.At5 ,
.Eaton ;
.Ox , Fx , Nx , No man-db , man-1.6
.br
.Nm apropos , whatis , mandoc :
.Ox 5.7 Pq August 27, 2014
.Pp
enable the named warning
.br
.Nm groff :
.No groff-0.5 Pq August 14, 1990
.Pp
only create the
.Xr whatis 1
database
.br
.Nm catman :
.Nx Pq July 27, 1993 ,
.No Solaris 9-11
.Pp
use wildcard matching
.br
.Nm apropos , whatis :
.No man-db-2.3.5 Pq April 21, 1995
.Pp
use manpath obtained from man --path
.br
.Nm makewhatis :
.man15g
.Pp
update the
.Xr whatis 1
database
.br
.Nm man :
.No illumos
.Pp
.Bq obsolete hardware
wait until the phototypesetter is available
.br
.Nm troff :
.At7
.It Fl X
display with
.Xr gxditview 1
.br
.Nm groff :
.No groff-1.06 Pq Sep 1, 1992
.br
.Nm man :
.dbI
.It Fl y
use the non-compacted version of the macros
.br
.Nm man :
.At3 ,
.At5
.It Fl Z
do not run preprocessors
.br
.Nm groff :
.g04
.br
.Nm man :
.No man-db-2.2a5 Pq Nov 10, 1994
.It Fl z
suppress formatted output from
.Xr troff 1 ,
print only error messages
.br
.Nm groff :
.g04
.It Fl 7
ASCII output mode
.br
.Nm man :
.No man-db-2.3.5 Pq April 21, 1995
.It Fl \&?
print a help message and exit
.br
.Nm groff :
.g04
.br
.Nm man , manpath :
.Eaton ;
.Fx , No man-db
.br
.Nm apropos , whatis , mandb , catman :
.dbI
.El
.Pp
Multi-letter options:
.Bl -tag -width Ds
.It Fl hp
.Bq obsolete hardware
output to a Hewlett Packard terminal
.br
.Nm man :
.PWB
.It Fl 12
.Bq obsolete hardware
use 12-pitch for certain terminals
.br
.Nm man :
.At3 ,
.At5
.It Fl 450
.Bq obsolete hardware
output to a DASI 450 terminal
.br
.Nm man :
.PWB
.El
.Pp
In
.At v3 ,
.Xr man 1
had no options.
.br
The syntax was:
.Sy man Ar name Op Ar section
.Pp
In
.At v4 ,
.br
the syntax changed to:
.Sy man Oo Ar section Oc Op Ar name ...
.Sh AUTHORS
This information was assembled by
.An Ingo Schwarze Aq Mt schwarze@openbsd.org
using
.Bl -bullet -compact
.It
the Unix Archive of the Unix Heritage Society
.It
the CSRG Archive CD-ROMs
.It
the
.Fx
SVN repository
.It
the
.Ox
CVS repository
.It
the
.Nx
CVS repository
.It
the GNU roff (groff) git repository
.It
the 4.3BSD-Net/2 groff CHANGES file (Oct 1990 to March 1991)
.It
the 4.3BSD-Net/2 groff ChangeLog file (July 1990 to March 1991)
.It
the man-db CVS and git repositories (since April 2001)
.It
the man-db NEWS file (April 1995 to Dec 2016)
.It
the man-db ChangeLog-2013 file (Nov 1994 to Dec 2013)
.It
release tarballs man-1.5g (July 1998) to man-1.5p (Jan 2005),
man-1.6 (June 2005), and man-1.6a to man-1.6g (Dec 2010)
.It
a makewhatis release tarball without version number from 1995
.It
the illumos manual pages on the WWW
.It
and Solaris 11, SunOS 5.10, and SunOS 5.9 machines at opencsw.org.
.El
mandoc-1.14.3/manconf.h 0100644 0002007 0000011 00000003037 13141336265 0014252 0 ustar 00schwarze wsrc /* $Id: manconf.h,v 1.5 2017/07/01 09:47:30 schwarze Exp $ */
/*
* Copyright (c) 2011, 2015, 2017 Ingo Schwarze <schwarze@openbsd.org>
* Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
/* List of unique, absolute paths to manual trees. */
struct manpaths {
char **paths;
size_t sz;
};
/* Data from -O options and man.conf(5) output directives. */
struct manoutput {
char *includes;
char *man;
char *paper;
char *style;
size_t indent;
size_t width;
int fragment;
int mdoc;
int synopsisonly;
int noval;
};
struct manconf {
struct manoutput output;
struct manpaths manpath;
};
void manconf_parse(struct manconf *, const char *, char *, char *);
int manconf_output(struct manoutput *, const char *, int);
void manconf_free(struct manconf *);
void manpath_base(struct manpaths *);
mandoc-1.14.3/mandoc.1 0100644 0002007 0000011 00000142751 13141336265 0014012 0 ustar 00schwarze wsrc .\" $Id: mandoc.1,v 1.217 2017/07/20 15:26:41 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: July 20 2017 $
.Dt MANDOC 1
.Os
.Sh NAME
.Nm mandoc
.Nd format manual pages
.Sh SYNOPSIS
.Nm mandoc
.Op Fl ac
.Op Fl I Cm os Ns = Ns Ar name
.Op Fl K Ar encoding
.Op Fl mdoc | man
.Op Fl O Ar options
.Op Fl T Ar output
.Op Fl W Ar level
.Op Ar
.Sh DESCRIPTION
The
.Nm
utility formats
.Ux
manual pages for display.
.Pp
By default,
.Nm
reads
.Xr mdoc 7
or
.Xr man 7
text from stdin and produces
.Fl T Cm locale
output.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl a
If the standard output is a terminal device and
.Fl c
is not specified, use
.Xr more 1
to paginate the output, just like
.Xr man 1
would.
.It Fl c
Copy the formatted manual pages to the standard output without using
.Xr more 1
to paginate them.
This is the default.
It can be specified to override
.Fl a .
.It Fl I Cm os Ns = Ns Ar name
Override the default operating system
.Ar name
for the
.Xr mdoc 7
.Ic \&Os
and for the
.Xr man 7
.Ic \&TH
macro.
.It Fl K Ar encoding
Specify the input encoding.
The supported
.Ar encoding
arguments are
.Cm us-ascii ,
.Cm iso-8859-1 ,
and
.Cm utf-8 .
If not specified, autodetection uses the first match in the following
list:
.Bl -enum
.It
If the first three bytes of the input file are the UTF-8 byte order
mark (BOM, 0xefbbbf), input is interpreted as
.Cm utf-8 .
.It
If the first or second line of the input file matches the
.Sy emacs
mode line format
.Pp
.D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*-
.Pp
then input is interpreted according to
.Ar encoding .
.It
If the first non-ASCII byte in the file introduces a valid UTF-8
sequence, input is interpreted as
.Cm utf-8 .
.It
Otherwise, input is interpreted as
.Cm iso-8859-1 .
.El
.It Fl mdoc | man
With
.Fl mdoc ,
all input files are interpreted as
.Xr mdoc 7 .
With
.Fl man ,
all input files are interpreted as
.Xr man 7 .
By default, the input language is automatically detected for each file:
if the the first macro is
.Ic \&Dd
or
.Ic \&Dt ,
the
.Xr mdoc 7
parser is used; otherwise, the
.Xr man 7
parser is used.
With other arguments,
.Fl m
is silently ignored.
.It Fl O Ar options
Comma-separated output options.
.It Fl T Ar output
Output format.
See
.Sx Output Formats
for available formats.
Defaults to
.Fl T Cm locale .
.It Fl W Ar level
Specify the minimum message
.Ar level
to be reported on the standard error output and to affect the exit status.
The
.Ar level
can be
.Cm base ,
.Cm style ,
.Cm warning ,
.Cm error ,
or
.Cm unsupp .
The
.Cm base
level automatically derives the operating system from the contents of the
.Ic \&Os
macro, from the
.Fl Ios
command line option, or from the
.Xr uname 3
return value.
The levels
.Cm openbsd
and
.Cm netbsd
are variants of
.Cm base
that bypass autodetection and request validation of base system
conventions for a particular operating system.
The level
.Cm all
is an alias for
.Cm base .
By default,
.Nm
is silent.
See
.Sx EXIT STATUS
and
.Sx DIAGNOSTICS
for details.
.Pp
The special option
.Fl W Cm stop
tells
.Nm
to exit after parsing a file that causes warnings or errors of at least
the requested level.
No formatted output will be produced from that file.
If both a
.Ar level
and
.Cm stop
are requested, they can be joined with a comma, for example
.Fl W Cm error , Ns Cm stop .
.It Ar file
Read input from zero or more files.
If unspecified, reads from stdin.
If multiple files are specified,
.Nm
will halt with the first failed parse.
.El
.Pp
The options
.Fl fhklw
are also supported and are documented in man(1).
In
.Fl f
and
.Fl k
mode,
.Nm
also supports the options
.Fl CMmOSs
described in the
.Xr apropos 1
manual.
The options
.Fl fkl
are mutually exclusive and override each other.
.Ss Output Formats
The
.Nm
utility accepts the following
.Fl T
arguments, which correspond to output modes:
.Bl -tag -width "-T markdown"
.It Fl T Cm ascii
Produce 7-bit ASCII output.
See
.Sx ASCII Output .
.It Fl T Cm html
Produce HTML5, CSS1, and MathML output.
See
.Sx HTML Output .
.It Fl T Cm lint
Parse only: produce no output.
Implies
.Fl W Cm all
and redirects parser messages, which usually appear
on standard error output, to standard output.
.It Fl T Cm locale
Encode output using the current locale.
This is the default.
See
.Sx Locale Output .
.It Fl T Cm man
Produce
.Xr man 7
format output.
See
.Sx Man Output .
.It Fl T Cm markdown
Produce output in
.Sy markdown
format.
See
.Sx Markdown Output .
.It Fl T Cm pdf
Produce PDF output.
See
.Sx PDF Output .
.It Fl T Cm ps
Produce PostScript output.
See
.Sx PostScript Output .
.It Fl T Cm tree
Produce an indented parse tree.
See
.Sx Syntax tree output .
.It Fl T Cm utf8
Encode output in the UTF\-8 multi-byte format.
See
.Sx UTF\-8 Output .
.El
.Pp
If multiple input files are specified, these will be processed by the
corresponding filter in-order.
.Ss ASCII Output
Output produced by
.Fl T Cm ascii
is rendered in standard 7-bit ASCII documented in
.Xr ascii 7 .
.Pp
Font styles are applied by using back-spaced encoding such that an
underlined character
.Sq c
is rendered as
.Sq _ Ns \e[bs] Ns c ,
where
.Sq \e[bs]
is the back-space character number 8.
Emboldened characters are rendered as
.Sq c Ns \e[bs] Ns c .
.Pp
The special characters documented in
.Xr mandoc_char 7
are rendered best-effort in an ASCII equivalent.
.Pp
Output width is limited to 78 visible columns unless literal input lines
exceed this limit.
.Pp
The following
.Fl O
arguments are accepted:
.Bl -tag -width Ds
.It Cm indent Ns = Ns Ar indent
The left margin for normal text is set to
.Ar indent
blank characters instead of the default of five for
.Xr mdoc 7
and seven for
.Xr man 7 .
Increasing this is not recommended; it may result in degraded formatting,
for example overfull lines or ugly line breaks.
.It Cm width Ns = Ns Ar width
The output width is set to
.Ar width .
.El
.Ss HTML Output
Output produced by
.Fl T Cm html
conforms to HTML5 using optional self-closing tags.
Default styles use only CSS1.
Equations rendered from
.Xr eqn 7
blocks use MathML.
.Pp
The
.Pa mandoc.css
file documents style-sheet classes available for customising output.
If a style-sheet is not specified with
.Fl O Cm style ,
.Fl T Cm html
defaults to simple output (via an embedded style-sheet)
readable in any graphical or text-based web
browser.
.Pp
Special characters are rendered in decimal-encoded UTF\-8.
.Pp
The following
.Fl O
arguments are accepted:
.Bl -tag -width Ds
.It Cm fragment
Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
elements and only emit the subtree below the <body> element.
The
.Cm style
argument will be ignored.
This is useful when embedding manual content within existing documents.
.It Cm includes Ns = Ns Ar fmt
The string
.Ar fmt ,
for example,
.Ar ../src/%I.html ,
is used as a template for linked header files (usually via the
.Ic \&In
macro).
Instances of
.Sq \&%I
are replaced with the include filename.
The default is not to present a
hyperlink.
.It Cm man Ns = Ns Ar fmt
The string
.Ar fmt ,
for example,
.Ar ../html%S/%N.%S.html ,
is used as a template for linked manuals (usually via the
.Ic \&Xr
macro).
Instances of
.Sq \&%N
and
.Sq %S
are replaced with the linked manual's name and section, respectively.
If no section is included, section 1 is assumed.
The default is not to
present a hyperlink.
.It Cm style Ns = Ns Ar style.css
The file
.Ar style.css
is used for an external style-sheet.
This must be a valid absolute or
relative URI.
.El
.Ss Locale Output
Locale-depending output encoding is triggered with
.Fl T Cm locale .
This is the default.
.Pp
This option is not available on all systems: systems without locale
support, or those whose internal representation is not natively UCS-4,
will fall back to
.Fl T Cm ascii .
See
.Sx ASCII Output
for font style specification and available command-line arguments.
.Ss Man Output
Translate input format into
.Xr man 7
output format.
This is useful for distributing manual sources to legacy systems
lacking
.Xr mdoc 7
formatters.
.Pp
If
.Xr mdoc 7
is passed as input, it is translated into
.Xr man 7 .
If the input format is
.Xr man 7 ,
the input is copied to the output, expanding any
.Xr roff 7
.Ic so
requests.
The parser is also run, and as usual, the
.Fl W
level controls which
.Sx DIAGNOSTICS
are displayed before copying the input to the output.
.Ss Markdown Output
Translate
.Xr mdoc 7
input to the
.Sy markdown
format conforming to
.Lk http://daringfireball.net/projects/markdown/syntax.text\
"John Gruber's 2004 specification" .
The output also almost conforms to the
.Lk http://commonmark.org/ CommonMark
specification.
.Pp
The character set used for the markdown output is ASCII.
Non-ASCII characters are encoded as HTML entities.
Since that is not possible in literal font contexts, because these
are rendered as code spans and code blocks in the markdown output,
non-ASCII characters are transliterated to ASCII approximations in
these contexts.
.Pp
Markdown is a very weak markup language, so all semantic markup is
lost, and even part of the presentational markup may be lost.
Do not use this as an intermediate step in converting to HTML;
instead, use
.Fl T Cm html
directly.
.Pp
The
.Xr man 7 ,
.Xr tbl 7 ,
and
.Xr eqn 7
input languages are not supported by
.Fl T Cm markdown
output mode.
.Ss PDF Output
PDF-1.1 output may be generated by
.Fl T Cm pdf .
See
.Sx PostScript Output
for
.Fl O
arguments and defaults.
.Ss PostScript Output
PostScript
.Qq Adobe-3.0
Level-2 pages may be generated by
.Fl T Cm ps .
Output pages default to letter sized and are rendered in the Times font
family, 11-point.
Margins are calculated as 1/9 the page length and width.
Line-height is 1.4m.
.Pp
Special characters are rendered as in
.Sx ASCII Output .
.Pp
The following
.Fl O
arguments are accepted:
.Bl -tag -width Ds
.It Cm paper Ns = Ns Ar name
The paper size
.Ar name
may be one of
.Ar a3 ,
.Ar a4 ,
.Ar a5 ,
.Ar legal ,
or
.Ar letter .
You may also manually specify dimensions as
.Ar NNxNN ,
width by height in millimetres.
If an unknown value is encountered,
.Ar letter
is used.
.El
.Ss UTF\-8 Output
Use
.Fl T Cm utf8
to force a UTF\-8 locale.
See
.Sx Locale Output
for details and options.
.Ss Syntax tree output
Use
.Fl T Cm tree
to show a human readable representation of the syntax tree.
It is useful for debugging the source code of manual pages.
The exact format is subject to change, so don't write parsers for it.
.Pp
The first paragraph shows meta data found in the
.Xr mdoc 7
prologue, on the
.Xr man 7
.Ic \&TH
line, or the fallbacks used.
.Pp
In the tree dump, each output line shows one syntax tree node.
Child nodes are indented with respect to their parent node.
The columns are:
.Pp
.Bl -enum -compact
.It
For macro nodes, the macro name; for text and
.Xr tbl 7
nodes, the content.
There is a special format for
.Xr eqn 7
nodes.
.It
Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
.It
Flags:
.Bl -dash -compact
.It
An opening parenthesis if the node is an opening delimiter.
.It
An asterisk if the node starts a new input line.
.It
The input line number (starting at one).
.It
A colon.
.It
The input column number (starting at one).
.It
A closing parenthesis if the node is a closing delimiter.
.It
A full stop if the node ends a sentence.
.It
BROKEN if the node is a block broken by another block.
.It
NOSRC if the node is not in the input file,
but automatically generated from macros.
.It
NOPRT if the node is not supposed to generate output
for any output format.
.El
.El
.Pp
The following
.Fl O
argument is accepted:
.Bl -tag -width Ds
.It Cm noval
Skip validation and show the unvalidated syntax tree.
This can help to find out whether a given behaviour is caused by
the parser or by the validator.
Meta data is not available in this case.
.El
.Sh ENVIRONMENT
.Bl -tag -width MANPAGER
.It Ev MANPAGER
Any non-empty value of the environment variable
.Ev MANPAGER
is used instead of the standard pagination program,
.Xr more 1 ;
see
.Xr man 1
for details.
Only used if
.Fl a
or
.Fl l
is specified.
.It Ev PAGER
Specifies the pagination program to use when
.Ev MANPAGER
is not defined.
If neither PAGER nor MANPAGER is defined,
.Xr more 1
.Fl s
is used.
Only used if
.Fl a
or
.Fl l
is specified.
.El
.Sh EXIT STATUS
The
.Nm
utility exits with one of the following values, controlled by the message
.Ar level
associated with the
.Fl W
option:
.Pp
.Bl -tag -width Ds -compact
.It 0
No base system convention violations, style suggestions, warnings,
or errors occurred, or those that did were ignored because they
were lower than the requested
.Ar level .
.It 1
At least one base system convention violation or style suggestion
occurred, but no warning or error, and
.Fl W Cm base
or
.Fl W Cm style
was specified.
.It 2
At least one warning occurred, but no error, and
.Fl W Cm warning
or a lower
.Ar level
was requested.
.It 3
At least one parsing error occurred,
but no unsupported feature was encountered, and
.Fl W Cm error
or a lower
.Ar level
was requested.
.It 4
At least one unsupported feature was encountered, and
.Fl W Cm unsupp
or a lower
.Ar level
was requested.
.It 5
Invalid command line arguments were specified.
No input files have been read.
.It 6
An operating system error occurred, for example exhaustion
of memory, file descriptors, or process table entries.
Such errors cause
.Nm
to exit at once, possibly in the middle of parsing or formatting a file.
.El
.Pp
Note that selecting
.Fl T Cm lint
output mode implies
.Fl W Cm all .
.Sh EXAMPLES
To page manuals to the terminal:
.Pp
.Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8
.Pp
To produce HTML manuals with
.Pa mandoc.css
as the style-sheet:
.Pp
.Dl $ mandoc \-T html -O style=mandoc.css mdoc.7 \*(Gt mdoc.7.html
.Pp
To check over a large set of manuals:
.Pp
.Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga
.Pp
To produce a series of PostScript manuals for A4 paper:
.Pp
.Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 \*(Gt manuals.ps
.Pp
Convert a modern
.Xr mdoc 7
manual to the older
.Xr man 7
format, for use on systems lacking an
.Xr mdoc 7
parser:
.Pp
.Dl $ mandoc \-T man foo.mdoc \*(Gt foo.man
.Sh DIAGNOSTICS
Messages displayed by
.Nm
follow this format:
.Bd -ragged -offset indent
.Nm :
.Ar file : Ns Ar line : Ns Ar column : level : message : macro args
.Pq Ar os
.Ed
.Pp
Line and column numbers start at 1.
Both are omitted for messages referring to an input file as a whole.
Macro names and arguments are omitted where meaningless.
The
.Ar os
operating system specifier is omitted for messages that are relevant
for all operating systems.
Fatal messages about invalid command line arguments
or operating system errors, for example when memory is exhausted,
may also omit the
.Ar file
and
.Ar level
fields.
.Pp
Message levels have the following meanings:
.Bl -tag -width "warning"
.It Cm unsupp
An input file uses unsupported low-level
.Xr roff 7
features.
The output may be incomplete and/or misformatted,
so using GNU troff instead of
.Nm
to process the file may be preferable.
.It Cm error
Indicates a risk of information loss or severe misformatting,
in most cases caused by serious syntax errors.
.It Cm warning
Indicates a risk that the information shown or its formatting
may mismatch the author's intent in minor ways.
Additionally, syntax errors are classified at least as warnings,
even if they do not usually cause misformatting.
.It Cm style
An input file uses dubious or discouraged style.
This is not a complaint about the syntax, and probably neither
formatting nor portability are in danger.
While great care is taken to avoid false positives on the higher
message levels, the
.Cm style
level tries to reduce the probability that issues go unnoticed,
so it may occasionally issue bogus suggestions.
Please use your good judgement to decide whether any particular
.Cm style
suggestion really justifies a change to the input file.
.It Cm base
A convertion used in the base system of a specific operating system
is not adhered to.
These are not markup mistakes, and neither the quality of formatting
nor portability are in danger.
Messages of the
.Cm base
level are printed with the more intuitive
.Cm style
.Ar level
tag.
.El
.Pp
Messages of the
.Cm base ,
.Cm style ,
.Cm warning ,
.Cm error ,
and
.Cm unsupp
levels except those about non-existent or unreadable input files
are hidden unless their level, or a lower level, is requested using a
.Fl W
option or
.Fl T Cm lint
output mode.
.Pp
As indicated below, all
.Cm base
and some
.Cm style
checks are only performed if a specific operating system name occurs
in the arguments of the
.Fl W
command line option, of the
.Ic \&Os
macro, of the
.Fl Ios
command line option, or, if neither are present, in the return value
of the
.Xr uname 3
function.
.Ss Conventions for base system manuals
.Bl -ohang
.It Sy "Mdocdate found"
.Pq mdoc , Nx
The
.Ic \&Dd
macro uses CVS
.Ic Mdocdate
keyword substitution, which is not supported by the
.Nx
base system.
Consider using the conventional
.Dq "Month dd, yyyy"
format instead.
.It Sy "Mdocdate missing"
.Pq mdoc , Ox
The
.Ic \&Dd
macro does not use CVS
.Ic Mdocdate
keyword substitution, but using it is conventionally expected in the
.Ox
base system.
.It Sy "unknown architecture"
.Pq mdoc , Ox , Nx
The third argument of the
.Ic \&Dt
macro does not match any of the architectures this operating system
is running on.
.It Sy "operating system explicitly specified"
.Pq mdoc , Ox , Nx
The
.Ic \&Os
macro has an argument.
In the base system, it is conventionally left blank.
.It Sy "RCS id missing"
.Pq Ox , Nx
The manual page lacks the comment line with the RCS identifier
generated by CVS
.Ic OpenBSD
or
.Ic NetBSD
keyword substitution as conventionally used in these operating systems.
.It Sy "referenced manual not found"
.Pq mdoc
An
.Ic \&Xr
macro references a manual page that is not found in the base system.
The path to look for base system manuals is configurable at compile
time and defaults to
.Pa /usr/share/man : /usr/X11R6/man .
.El
.Ss Style suggestions
.Bl -ohang
.It Sy "legacy man(7) date format"
.Pq mdoc
The
.Ic \&Dd
macro uses the legacy
.Xr man 7
date format
.Dq yyyy-dd-mm .
Consider using the conventional
.Xr mdoc 7
date format
.Dq "Month dd, yyyy"
instead.
.It Sy "lower case character in document title"
.Pq mdoc , man
The title is still used as given in the
.Ic \&Dt
or
.Ic \&TH
macro.
.It Sy "duplicate RCS id"
A single manual page contains two copies of the RCS identifier for
the same operating system.
Consider deleting the later instance and moving the first one up
to the top of the page.
.It Sy "typo in section name"
.Pq mdoc
Fuzzy string matching revealed that the argument of an
.Ic \&Sh
macro is similar, but not identical to a standard section name.
.It Sy "unterminated quoted argument"
.Pq roff
Macro arguments can be enclosed in double quote characters
such that space characters and macro names contained in the quoted
argument need not be escaped.
The closing quote of the last argument of a macro can be omitted.
However, omitting it is not recommended because it makes the code
harder to read.
.It Sy "useless macro"
.Pq mdoc
A
.Ic \&Bt ,
.Ic \&Tn ,
or
.Ic \&Ud
macro was found.
Simply delete it: it serves no useful purpose.
.It Sy "consider using OS macro"
.Pq mdoc
A string was found in plain text or in a
.Ic \&Bx
macro that could be represented using
.Ic \&Ox ,
.Ic \&Nx ,
.Ic \&Fx ,
or
.Ic \&Dx .
.It Sy "errnos out of order"
.Pq mdoc, Nx
The
.Ic \&Er
items in a
.Ic \&Bl
list are not in alphabetical order.
.It Sy "duplicate errno"
.Pq mdoc, Nx
A
.Ic \&Bl
list contains two consecutive
.Ic \&It
entries describing the same
.Ic \&Er
number.
.It Sy "trailing delimiter"
.Pq mdoc
The last argument of an
.Ic \&Ex , \&Fo , \&Nd , \&Nm , \&Os , \&Sh , \&Ss , \&St ,
or
.Ic \&Sx
macro ends with a trailing delimiter.
This is usually bad style and often indicates typos.
Most likely, the delimiter can be removed.
.It Sy "no blank before trailing delimiter"
.Pq mdoc
The last argument of a macro that supports trailing delimiter
arguments is longer than one byte and ends with a trailing delimiter.
Consider inserting a blank such that the delimiter becomes a separate
argument, thus moving it out of the scope of the macro.
.It Sy "fill mode already enabled, skipping"
.Pq man
A
.Ic \&fi
request occurs even though the document is still in fill mode,
or already switched back to fill mode.
It has no effect.
.It Sy "fill mode already disabled, skipping"
.Pq man
An
.Ic \&nf
request occurs even though the document already switched to no-fill mode
and did not switch back to fill mode yet.
It has no effect.
.It Sy "function name without markup"
.Pq mdoc
A word followed by an empty pair of parentheses occurs on a text line.
Consider using an
.Ic \&Fn
or
.Ic \&Xr
macro.
.It Sy "whitespace at end of input line"
.Pq mdoc , man , roff
Whitespace at the end of input lines is almost never semantically
significant \(em but in the odd case where it might be, it is
extremely confusing when reviewing and maintaining documents.
.It Sy "bad comment style"
.Pq roff
Comment lines start with a dot, a backslash, and a double-quote character.
The
.Nm
utility treats the line as a comment line even without the backslash,
but leaving out the backslash might not be portable.
.El
.Ss Warnings related to the document prologue
.Bl -ohang
.It Sy "missing manual title, using UNTITLED"
.Pq mdoc
A
.Ic \&Dt
macro has no arguments, or there is no
.Ic \&Dt
macro before the first non-prologue macro.
.It Sy "missing manual title, using \(dq\(dq"
.Pq man
There is no
.Ic \&TH
macro, or it has no arguments.
.It Sy "missing manual section, using \(dq\(dq"
.Pq mdoc , man
A
.Ic \&Dt
or
.Ic \&TH
macro lacks the mandatory section argument.
.It Sy "unknown manual section"
.Pq mdoc
The section number in a
.Ic \&Dt
line is invalid, but still used.
.It Sy "missing date, using today's date"
.Pq mdoc, man
The document was parsed as
.Xr mdoc 7
and it has no
.Ic \&Dd
macro, or the
.Ic \&Dd
macro has no arguments or only empty arguments;
or the document was parsed as
.Xr man 7
and it has no
.Ic \&TH
macro, or the
.Ic \&TH
macro has less than three arguments or its third argument is empty.
.It Sy "cannot parse date, using it verbatim"
.Pq mdoc , man
The date given in a
.Ic \&Dd
or
.Ic \&TH
macro does not follow the conventional format.
.It Sy "date in the future, using it anyway"
.Pq mdoc , man
The date given in a
.Ic \&Dd
or
.Ic \&TH
macro is more than a day ahead of the current system
.Xr time 3 .
.It Sy "missing Os macro, using \(dq\(dq"
.Pq mdoc
The default or current system is not shown in this case.
.It Sy "late prologue macro"
.Pq mdoc
A
.Ic \&Dd
or
.Ic \&Os
macro occurs after some non-prologue macro, but still takes effect.
.It Sy "prologue macros out of order"
.Pq mdoc
The prologue macros are not given in the conventional order
.Ic \&Dd ,
.Ic \&Dt ,
.Ic \&Os .
All three macros are used even when given in another order.
.El
.Ss Warnings regarding document structure
.Bl -ohang
.It Sy ".so is fragile, better use ln(1)"
.Pq roff
Including files only works when the parser program runs with the correct
current working directory.
.It Sy "no document body"
.Pq mdoc , man
The document body contains neither text nor macros.
An empty document is shown, consisting only of a header and a footer line.
.It Sy "content before first section header"
.Pq mdoc , man
Some macros or text precede the first
.Ic \&Sh
or
.Ic \&SH
section header.
The offending macros and text are parsed and added to the top level
of the syntax tree, outside any section block.
.It Sy "first section is not NAME"
.Pq mdoc
The argument of the first
.Ic \&Sh
macro is not
.Sq NAME .
This may confuse
.Xr makewhatis 8
and
.Xr apropos 1 .
.It Sy "NAME section without Nm before Nd"
.Pq mdoc
The NAME section does not contain any
.Ic \&Nm
child macro before the first
.Ic \&Nd
macro.
.It Sy "NAME section without description"
.Pq mdoc
The NAME section lacks the mandatory
.Ic \&Nd
child macro.
.It Sy "description not at the end of NAME"
.Pq mdoc
The NAME section does contain an
.Ic \&Nd
child macro, but other content follows it.
.It Sy "bad NAME section content"
.Pq mdoc
The NAME section contains plain text or macros other than
.Ic \&Nm
and
.Ic \&Nd .
.It Sy "missing comma before name"
.Pq mdoc
The NAME section contains an
.Ic \&Nm
macro that is neither the first one nor preceded by a comma.
.It Sy "missing description line, using \(dq\(dq"
.Pq mdoc
The
.Ic \&Nd
macro lacks the required argument.
The title line of the manual will end after the dash.
.It Sy "description line outside NAME section"
.Pq mdoc
An
.Ic \&Nd
macro appears outside the NAME section.
The arguments are printed anyway and the following text is used for
.Xr apropos 1 ,
but none of that behaviour is portable.
.It Sy "sections out of conventional order"
.Pq mdoc
A standard section occurs after another section it usually precedes.
All section titles are used as given,
and the order of sections is not changed.
.It Sy "duplicate section title"
.Pq mdoc
The same standard section title occurs more than once.
.It Sy "unexpected section"
.Pq mdoc
A standard section header occurs in a section of the manual
where it normally isn't useful.
.It Sy "cross reference to self"
.Pq mdoc
An
.Ic \&Xr
macro refers to a name and section matching the section of the present
manual page and a name mentioned in an
.Ic \&Nm
macro in the NAME or SYNOPSIS section, or in an
.Ic \&Fn
or
.Ic \&Fo
macro in the SYNOPSIS.
Consider using
.Ic \&Nm
or
.Ic \&Fn
instead of
.Ic \&Xr .
.It Sy "unusual Xr order"
.Pq mdoc
In the SEE ALSO section, an
.Ic \&Xr
macro with a lower section number follows one with a higher number,
or two
.Ic \&Xr
macros referring to the same section are out of alphabetical order.
.It Sy "unusual Xr punctuation"
.Pq mdoc
In the SEE ALSO section, punctuation between two
.Ic \&Xr
macros differs from a single comma, or there is trailing punctuation
after the last
.Ic \&Xr
macro.
.It Sy "AUTHORS section without An macro"
.Pq mdoc
An AUTHORS sections contains no
.Ic \&An
macros, or only empty ones.
Probably, there are author names lacking markup.
.El
.Ss "Warnings related to macros and nesting"
.Bl -ohang
.It Sy "obsolete macro"
.Pq mdoc
See the
.Xr mdoc 7
manual for replacements.
.It Sy "macro neither callable nor escaped"
.Pq mdoc
The name of a macro that is not callable appears on a macro line.
It is printed verbatim.
If the intention is to call it, move it to its own input line;
otherwise, escape it by prepending
.Sq \e& .
.It Sy "skipping paragraph macro"
In
.Xr mdoc 7
documents, this happens
.Bl -dash -compact
.It
at the beginning and end of sections and subsections
.It
right before non-compact lists and displays
.It
at the end of items in non-column, non-compact lists
.It
and for multiple consecutive paragraph macros.
.El
In
.Xr man 7
documents, it happens
.Bl -dash -compact
.It
for empty
.Ic \&P ,
.Ic \&PP ,
and
.Ic \&LP
macros
.It
for
.Ic \&IP
macros having neither head nor body arguments
.It
for
.Ic \&br
or
.Ic \&sp
right after
.Ic \&SH
or
.Ic \&SS
.El
.It Sy "moving paragraph macro out of list"
.Pq mdoc
A list item in a
.Ic \&Bl
list contains a trailing paragraph macro.
The paragraph macro is moved after the end of the list.
.It Sy "skipping no-space macro"
.Pq mdoc
An input line begins with an
.Ic \&Ns
macro, or the next argument after an
.Ic \&Ns
macro is an isolated closing delimiter.
The macro is ignored.
.It Sy "blocks badly nested"
.Pq mdoc
If two blocks intersect, one should completely contain the other.
Otherwise, rendered output is likely to look strange in any output
format, and rendering in SGML-based output formats is likely to be
outright wrong because such languages do not support badly nested
blocks at all.
Typical examples of badly nested blocks are
.Qq Ic \&Ao \&Bo \&Ac \&Bc
and
.Qq Ic \&Ao \&Bq \&Ac .
In these examples,
.Ic \&Ac
breaks
.Ic \&Bo
and
.Ic \&Bq ,
respectively.
.It Sy "nested displays are not portable"
.Pq mdoc
A
.Ic \&Bd ,
.Ic \&D1 ,
or
.Ic \&Dl
display occurs nested inside another
.Ic \&Bd
display.
This works with
.Nm ,
but fails with most other implementations.
.It Sy "moving content out of list"
.Pq mdoc
A
.Ic \&Bl
list block contains text or macros before the first
.Ic \&It
macro.
The offending children are moved before the beginning of the list.
.It Sy "first macro on line"
Inside a
.Ic \&Bl Fl column
list, a
.Ic \&Ta
macro occurs as the first macro on a line, which is not portable.
.It Sy "line scope broken"
.Pq man
While parsing the next-line scope of the previous macro,
another macro is found that prematurely terminates the previous one.
The previous, interrupted macro is deleted from the parse tree.
.El
.Ss "Warnings related to missing arguments"
.Bl -ohang
.It Sy "skipping empty request"
.Pq roff , eqn
The macro name is missing from a macro definition request,
or an
.Xr eqn 7
control statement or operation keyword lacks its required argument.
.It Sy "conditional request controls empty scope"
.Pq roff
A conditional request is only useful if any of the following
follows it on the same logical input line:
.Bl -dash -compact
.It
The
.Sq \e{
keyword to open a multi-line scope.
.It
A request or macro or some text, resulting in a single-line scope.
.It
The immediate end of the logical line without any intervening whitespace,
resulting in next-line scope.
.El
Here, a conditional request is followed by trailing whitespace only,
and there is no other content on its logical input line.
Note that it doesn't matter whether the logical input line is split
across multiple physical input lines using
.Sq \e
line continuation characters.
This is one of the rare cases
where trailing whitespace is syntactically significant.
The conditional request controls a scope containing whitespace only,
so it is unlikely to have a significant effect,
except that it may control a following
.Ic \&el
clause.
.It Sy "skipping empty macro"
.Pq mdoc
The indicated macro has no arguments and hence no effect.
.It Sy "empty block"
.Pq mdoc , man
A
.Ic \&Bd ,
.Ic \&Bk ,
.Ic \&Bl ,
.Ic \&D1 ,
.Ic \&Dl ,
.Ic \&MT ,
.Ic \&RS ,
or
.Ic \&UR
block contains nothing in its body and will produce no output.
.It Sy "empty argument, using 0n"
.Pq mdoc
The required width is missing after
.Ic \&Bd
or
.Ic \&Bl
.Fl offset
or
.Fl width .
.It Sy "missing display type, using -ragged"
.Pq mdoc
The
.Ic \&Bd
macro is invoked without the required display type.
.It Sy "list type is not the first argument"
.Pq mdoc
In a
.Ic \&Bl
macro, at least one other argument precedes the type argument.
The
.Nm
utility copes with any argument order, but some other
.Xr mdoc 7
implementations do not.
.It Sy "missing -width in -tag list, using 8n"
.Pq mdoc
Every
.Ic \&Bl
macro having the
.Fl tag
argument requires
.Fl width ,
too.
.It Sy "missing utility name, using \(dq\(dq"
.Pq mdoc
The
.Ic \&Ex Fl std
macro is called without an argument before
.Ic \&Nm
has first been called with an argument.
.It Sy "missing function name, using \(dq\(dq"
.Pq mdoc
The
.Ic \&Fo
macro is called without an argument.
No function name is printed.
.It Sy "empty head in list item"
.Pq mdoc
In a
.Ic \&Bl
.Fl diag ,
.Fl hang ,
.Fl inset ,
.Fl ohang ,
or
.Fl tag
list, an
.Ic \&It
macro lacks the required argument.
The item head is left empty.
.It Sy "empty list item"
.Pq mdoc
In a
.Ic \&Bl
.Fl bullet ,
.Fl dash ,
.Fl enum ,
or
.Fl hyphen
list, an
.Ic \&It
block is empty.
An empty list item is shown.
.It Sy "missing argument, using next line"
.Pq mdoc
An
.Ic \&It
macro in a
.Ic \&Bd Fl column
list has no arguments.
While
.Nm
uses the text or macros of the following line, if any, for the cell,
other formatters may misformat the list.
.It Sy "missing font type, using \efR"
.Pq mdoc
A
.Ic \&Bf
macro has no argument.
It switches to the default font.
.It Sy "unknown font type, using \efR"
.Pq mdoc
The
.Ic \&Bf
argument is invalid.
The default font is used instead.
.It Sy "nothing follows prefix"
.Pq mdoc
A
.Ic \&Pf
macro has no argument, or only one argument and no macro follows
on the same input line.
This defeats its purpose; in particular, spacing is not suppressed
before the text or macros following on the next input line.
.It Sy "empty reference block"
.Pq mdoc
An
.Ic \&Rs
macro is immediately followed by an
.Ic \&Re
macro on the next input line.
Such an empty block does not produce any output.
.It Sy "missing section argument"
.Pq mdoc
An
.Ic \&Xr
macro lacks its second, section number argument.
The first argument, i.e. the name, is printed, but without subsequent
parentheses.
.It Sy "missing -std argument, adding it"
.Pq mdoc
An
.Ic \&Ex
or
.Ic \&Rv
macro lacks the required
.Fl std
argument.
The
.Nm
utility assumes
.Fl std
even when it is not specified, but other implementations may not.
.It Sy "missing option string, using \(dq\(dq"
.Pq man
The
.Ic \&OP
macro is invoked without any argument.
An empty pair of square brackets is shown.
.It Sy "missing resource identifier, using \(dq\(dq"
.Pq man
The
.Ic \&MT
or
.Ic \&UR
macro is invoked without any argument.
An empty pair of angle brackets is shown.
.It Sy "missing eqn box, using \(dq\(dq"
.Pq eqn
A diacritic mark or a binary operator is found,
but there is nothing to the left of it.
An empty box is inserted.
.El
.Ss "Warnings related to bad macro arguments"
.Bl -ohang
.It Sy "duplicate argument"
.Pq mdoc
A
.Ic \&Bd
or
.Ic \&Bl
macro has more than one
.Fl compact ,
more than one
.Fl offset ,
or more than one
.Fl width
argument.
All but the last instances of these arguments are ignored.
.It Sy "skipping duplicate argument"
.Pq mdoc
An
.Ic \&An
macro has more than one
.Fl split
or
.Fl nosplit
argument.
All but the first of these arguments are ignored.
.It Sy "skipping duplicate display type"
.Pq mdoc
A
.Ic \&Bd
macro has more than one type argument; the first one is used.
.It Sy "skipping duplicate list type"
.Pq mdoc
A
.Ic \&Bl
macro has more than one type argument; the first one is used.
.It Sy "skipping -width argument"
.Pq mdoc
A
.Ic \&Bl
.Fl column ,
.Fl diag ,
.Fl ohang ,
.Fl inset ,
or
.Fl item
list has a
.Fl width
argument.
That has no effect.
.It Sy "wrong number of cells"
In a line of a
.Ic \&Bl Fl column
list, the number of tabs or
.Ic \&Ta
macros is less than the number expected from the list header line
or exceeds the expected number by more than one.
Missing cells remain empty, and all cells exceeding the number of
columns are joined into one single cell.
.It Sy "unknown AT&T UNIX version"
.Pq mdoc
An
.Ic \&At
macro has an invalid argument.
It is used verbatim, with
.Qq "AT&T UNIX "
prefixed to it.
.It Sy "comma in function argument"
.Pq mdoc
An argument of an
.Ic \&Fa
or
.Ic \&Fn
macro contains a comma; it should probably be split into two arguments.
.It Sy "parenthesis in function name"
.Pq mdoc
The first argument of an
.Ic \&Fc
or
.Ic \&Fn
macro contains an opening or closing parenthesis; that's probably wrong,
parentheses are added automatically.
.It Sy "unknown library name"
.Pq mdoc, not on Ox
An
.Ic \&Lb
macro has an unknown name argument and will be rendered as
.Qq library Dq Ar name .
.It Sy "invalid content in Rs block"
.Pq mdoc
An
.Ic \&Rs
block contains plain text or non-% macros.
The bogus content is left in the syntax tree.
Formatting may be poor.
.It Sy "invalid Boolean argument"
.Pq mdoc
An
.Ic \&Sm
macro has an argument other than
.Cm on
or
.Cm off .
The invalid argument is moved out of the macro, which leaves the macro
empty, causing it to toggle the spacing mode.
.It Sy "unknown font, skipping request"
.Pq man , tbl
A
.Xr roff 7
.Ic \&ft
request or a
.Xr tbl 7
.Ic \&f
layout modifier has an unknown
.Ar font
argument.
.It Sy "odd number of characters in request"
.Pq roff
A
.Ic \&tr
request contains an odd number of characters.
The last character is mapped to the blank character.
.El
.Ss "Warnings related to plain text"
.Bl -ohang
.It Sy "blank line in fill mode, using .sp"
.Pq mdoc
The meaning of blank input lines is only well-defined in non-fill mode:
In fill mode, line breaks of text input lines are not supposed to be
significant.
However, for compatibility with groff, blank lines in fill mode
are replaced with
.Ic \&sp
requests.
.It Sy "tab in filled text"
.Pq mdoc , man
The meaning of tab characters is only well-defined in non-fill mode:
In fill mode, whitespace is not supposed to be significant
on text input lines.
As an implementation dependent choice, tab characters on text lines
are passed through to the formatters in any case.
Given that the text before the tab character will be filled,
it is hard to predict which tab stop position the tab will advance to.
.It Sy "new sentence, new line"
.Pq mdoc
A new sentence starts in the middle of a text line.
Start it on a new input line to help formatters produce correct spacing.
.It Sy "invalid escape sequence"
.Pq roff
An escape sequence has an invalid opening argument delimiter, lacks the
closing argument delimiter, or the argument has too few characters.
If the argument is incomplete,
.Ic \e*
and
.Ic \en
expand to an empty string,
.Ic \eB
to the digit
.Sq 0 ,
and
.Ic \ew
to the length of the incomplete argument.
All other invalid escape sequences are ignored.
.It Sy "undefined string, using \(dq\(dq"
.Pq roff
If a string is used without being defined before,
its value is implicitly set to the empty string.
However, defining strings explicitly before use
keeps the code more readable.
.El
.Ss "Warnings related to tables"
.Bl -ohang
.It Sy "tbl line starts with span"
.Pq tbl
The first cell in a table layout line is a horizontal span
.Pq Sq Cm s .
Data provided for this cell is ignored, and nothing is printed in the cell.
.It Sy "tbl column starts with span"
.Pq tbl
The first line of a table layout specification
requests a vertical span
.Pq Sq Cm ^ .
Data provided for this cell is ignored, and nothing is printed in the cell.
.It Sy "skipping vertical bar in tbl layout"
.Pq tbl
A table layout specification contains more than two consecutive vertical bars.
A double bar is printed, all additional bars are discarded.
.El
.Ss "Errors related to tables"
.Bl -ohang
.It Sy "non-alphabetic character in tbl options"
.Pq tbl
The table options line contains a character other than a letter,
blank, or comma where the beginning of an option name is expected.
The character is ignored.
.It Sy "skipping unknown tbl option"
.Pq tbl
The table options line contains a string of letters that does not
match any known option name.
The word is ignored.
.It Sy "missing tbl option argument"
.Pq tbl
A table option that requires an argument is not followed by an
opening parenthesis, or the opening parenthesis is immediately
followed by a closing parenthesis.
The option is ignored.
.It Sy "wrong tbl option argument size"
.Pq tbl
A table option argument contains an invalid number of characters.
Both the option and the argument are ignored.
.It Sy "empty tbl layout"
.Pq tbl
A table layout specification is completely empty,
specifying zero lines and zero columns.
As a fallback, a single left-justified column is used.
.It Sy "invalid character in tbl layout"
.Pq tbl
A table layout specification contains a character that can neither
be interpreted as a layout key character nor as a layout modifier,
or a modifier precedes the first key.
The invalid character is discarded.
.It Sy "unmatched parenthesis in tbl layout"
.Pq tbl
A table layout specification contains an opening parenthesis,
but no matching closing parenthesis.
The rest of the input line, starting from the parenthesis, has no effect.
.It Sy "tbl without any data cells"
.Pq tbl
A table does not contain any data cells.
It will probably produce no output.
.It Sy "ignoring data in spanned tbl cell"
.Pq tbl
A table cell is marked as a horizontal span
.Pq Sq Cm s
or vertical span
.Pq Sq Cm ^
in the table layout, but it contains data.
The data is ignored.
.It Sy "ignoring extra tbl data cells"
.Pq tbl
A data line contains more cells than the corresponding layout line.
The data in the extra cells is ignored.
.It Sy "data block open at end of tbl"
.Pq tbl
A data block is opened with
.Cm T{ ,
but never closed with a matching
.Cm T} .
The remaining data lines of the table are all put into one cell,
and any remaining cells stay empty.
.El
.Ss "Errors related to roff, mdoc, and man code"
.Bl -ohang
.It Sy "duplicate prologue macro"
.Pq mdoc
One of the prologue macros occurs more than once.
The last instance overrides all previous ones.
.It Sy "skipping late title macro"
.Pq mdoc
The
.Ic \&Dt
macro appears after the first non-prologue macro.
Traditional formatters cannot handle this because
they write the page header before parsing the document body.
Even though this technical restriction does not apply to
.Nm ,
traditional semantics is preserved.
The late macro is discarded including its arguments.
.It Sy "input stack limit exceeded, infinite loop?"
.Pq roff
Explicit recursion limits are implemented for the following features,
in order to prevent infinite loops:
.Bl -dash -compact
.It
expansion of nested escape sequences
including expansion of strings and number registers,
.It
expansion of nested user-defined macros,
.It
and
.Ic \&so
file inclusion.
.El
When a limit is hit, the output is incorrect, typically losing
some content, but the parser can continue.
.It Sy "skipping bad character"
.Pq mdoc , man , roff
The input file contains a byte that is not a printable
.Xr ascii 7
character.
The message mentions the character number.
The offending byte is replaced with a question mark
.Pq Sq \&? .
Consider editing the input file to replace the byte with an ASCII
transliteration of the intended character.
.It Sy "skipping unknown macro"
.Pq mdoc , man , roff
The first identifier on a request or macro line is neither recognized as a
.Xr roff 7
request, nor as a user-defined macro, nor, respectively, as an
.Xr mdoc 7
or
.Xr man 7
macro.
It may be mistyped or unsupported.
The request or macro is discarded including its arguments.
.It Sy "skipping insecure request"
.Pq roff
An input file attempted to run a shell command
or to read or write an external file.
Such attempts are denied for security reasons.
.It Sy "skipping item outside list"
.Pq mdoc , eqn
An
.Ic \&It
macro occurs outside any
.Ic \&Bl
list, or an
.Xr eqn 7
.Ic above
delimiter occurs outside any pile.
It is discarded including its arguments.
.It Sy "skipping column outside column list"
.Pq mdoc
A
.Ic \&Ta
macro occurs outside any
.Ic \&Bl Fl column
block.
It is discarded including its arguments.
.It Sy "skipping end of block that is not open"
.Pq mdoc , man , eqn , tbl , roff
Various syntax elements can only be used to explicitly close blocks
that have previously been opened.
An
.Xr mdoc 7
block closing macro, a
.Xr man 7
.Ic \&ME , \&RE
or
.Ic \&UE
macro, an
.Xr eqn 7
right delimiter or closing brace, or the end of an equation, table, or
.Xr roff 7
conditional request is encountered but no matching block is open.
The offending request or macro is discarded.
.It Sy "fewer RS blocks open, skipping"
.Pq man
The
.Ic \&RE
macro is invoked with an argument, but less than the specified number of
.Ic \&RS
blocks is open.
The
.Ic \&RE
macro is discarded.
.It Sy "inserting missing end of block"
.Pq mdoc , tbl
Various
.Xr mdoc 7
macros as well as tables require explicit closing by dedicated macros.
A block that doesn't support bad nesting
ends before all of its children are properly closed.
The open child nodes are closed implicitly.
.It Sy "appending missing end of block"
.Pq mdoc , man , eqn , tbl , roff
At the end of the document, an explicit
.Xr mdoc 7
block, a
.Xr man 7
next-line scope or
.Ic \&MT , \&RS
or
.Ic \&UR
block, an equation, table, or
.Xr roff 7
conditional or ignore block is still open.
The open block is closed implicitly.
.It Sy "escaped character not allowed in a name"
.Pq roff
Macro, string and register identifiers consist of printable,
non-whitespace ASCII characters.
Escape sequences and characters and strings expressed in terms of them
cannot form part of a name.
The first argument of an
.Ic \&am ,
.Ic \&as ,
.Ic \&de ,
.Ic \&ds ,
.Ic \&nr ,
or
.Ic \&rr
request, or any argument of an
.Ic \&rm
request, or the name of a request or user defined macro being called,
is terminated by an escape sequence.
In the cases of
.Ic \&as ,
.Ic \&ds ,
and
.Ic \&nr ,
the request has no effect at all.
In the cases of
.Ic \&am ,
.Ic \&de ,
.Ic \&rr ,
and
.Ic \&rm ,
what was parsed up to this point is used as the arguments to the request,
and the rest of the input line is discarded including the escape sequence.
When parsing for a request or a user-defined macro name to be called,
only the escape sequence is discarded.
The characters preceding it are used as the request or macro name,
the characters following it are used as the arguments to the request or macro.
.It Sy "NOT IMPLEMENTED: Bd -file"
.Pq mdoc
For security reasons, the
.Ic \&Bd
macro does not support the
.Fl file
argument.
By requesting the inclusion of a sensitive file, a malicious document
might otherwise trick a privileged user into inadvertently displaying
the file on the screen, revealing the file content to bystanders.
The argument is ignored including the file name following it.
.It Sy "skipping display without arguments"
.Pq mdoc
A
.Ic \&Bd
block macro does not have any arguments.
The block is discarded, and the block content is displayed in
whatever mode was active before the block.
.It Sy "missing list type, using -item"
.Pq mdoc
A
.Ic \&Bl
macro fails to specify the list type.
.It Sy "argument is not numeric, using 1"
.Pq roff
The argument of a
.Ic \&ce
request is not a number.
.It Sy "missing manual name, using \(dq\(dq"
.Pq mdoc
The first call to
.Ic \&Nm ,
or any call in the NAME section, lacks the required argument.
.It Sy "uname(3) system call failed, using UNKNOWN"
.Pq mdoc
The
.Ic \&Os
macro is called without arguments, and the
.Xr uname 3
system call failed.
As a workaround,
.Nm
can be compiled with
.Sm off
.Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
.Sm on
.It Sy "unknown standard specifier"
.Pq mdoc
An
.Ic \&St
macro has an unknown argument and is discarded.
.It Sy "skipping request without numeric argument"
.Pq roff , eqn
An
.Ic \&it
request or an
.Xr eqn 7
.Ic \&size
or
.Ic \&gsize
statement has a non-numeric or negative argument or no argument at all.
The invalid request or statement is ignored.
.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
.Pq roff
For security reasons,
.Nm
allows
.Ic \&so
file inclusion requests only with relative paths
and only without ascending to any parent directory.
By requesting the inclusion of a sensitive file, a malicious document
might otherwise trick a privileged user into inadvertently displaying
the file on the screen, revealing the file content to bystanders.
.Nm
only shows the path as it appears behind
.Ic \&so .
.It Sy ".so request failed"
.Pq roff
Servicing a
.Ic \&so
request requires reading an external file, but the file could not be
opened.
.Nm
only shows the path as it appears behind
.Ic \&so .
.It Sy "skipping all arguments"
.Pq mdoc , man , eqn , roff
An
.Xr mdoc 7
.Ic \&Bt ,
.Ic \&Ed ,
.Ic \&Ef ,
.Ic \&Ek ,
.Ic \&El ,
.Ic \&Lp ,
.Ic \&Pp ,
.Ic \&Re ,
.Ic \&Rs ,
or
.Ic \&Ud
macro, an
.Ic \&It
macro in a list that don't support item heads, a
.Xr man 7
.Ic \&LP ,
.Ic \&P ,
or
.Ic \&PP
macro, an
.Xr eqn 7
.Ic \&EQ
or
.Ic \&EN
macro, or a
.Xr roff 7
.Ic \&br ,
.Ic \&fi ,
or
.Ic \&nf
request or
.Sq \&..
block closing request is invoked with at least one argument.
All arguments are ignored.
.It Sy "skipping excess arguments"
.Pq mdoc , man , roff
A macro or request is invoked with too many arguments:
.Bl -dash -offset 2n -width 2n -compact
.It
.Ic \&Fo ,
.Ic \&MT ,
.Ic \&PD ,
.Ic \&RS ,
.Ic \&UR ,
.Ic \&ft ,
or
.Ic \&sp
with more than one argument
.It
.Ic \&An
with another argument after
.Fl split
or
.Fl nosplit
.It
.Ic \&RE
with more than one argument or with a non-integer argument
.It
.Ic \&OP
or a request of the
.Ic \&de
family with more than two arguments
.It
.Ic \&Dt
with more than three arguments
.It
.Ic \&TH
with more than five arguments
.It
.Ic \&Bd ,
.Ic \&Bk ,
or
.Ic \&Bl
with invalid arguments
.El
The excess arguments are ignored.
.El
.Ss Unsupported features
.Bl -ohang
.It Sy "input too large"
.Pq mdoc , man
Currently,
.Nm
cannot handle input files larger than its arbitrary size limit
of 2^31 bytes (2 Gigabytes).
Since useful manuals are always small, this is not a problem in practice.
Parsing is aborted as soon as the condition is detected.
.It Sy "unsupported control character"
.Pq roff
An ASCII control character supported by other
.Xr roff 7
implementations but not by
.Nm
was found in an input file.
It is replaced by a question mark.
.It Sy "unsupported roff request"
.Pq roff
An input file contains a
.Xr roff 7
request supported by GNU troff or Heirloom troff but not by
.Nm ,
and it is likely that this will cause information loss
or considerable misformatting.
.It Sy "eqn delim option in tbl"
.Pq eqn , tbl
The options line of a table defines equation delimiters.
Any equation source code contained in the table will be printed unformatted.
.It Sy "unsupported table layout modifier"
.Pq tbl
A table layout specification contains an
.Sq Cm m
modifier.
The modifier is discarded.
.It Sy "ignoring macro in table"
.Pq tbl , mdoc , man
A table contains an invocation of an
.Xr mdoc 7
or
.Xr man 7
macro or of an undefined macro.
The macro is ignored, and its arguments are handled
as if they were a text line.
.El
.Sh SEE ALSO
.Xr apropos 1 ,
.Xr man 1 ,
.Xr eqn 7 ,
.Xr man 7 ,
.Xr mandoc_char 7 ,
.Xr mdoc 7 ,
.Xr roff 7 ,
.Xr tbl 7
.Sh HISTORY
The
.Nm
utility first appeared in
.Ox 4.8 .
The option
.Fl I
appeared in
.Ox 5.2 ,
and
.Fl aCcfhKklMSsw
in
.Ox 5.7 .
.Sh AUTHORS
.An -nosplit
The
.Nm
utility was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
and is maintained by
.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
mandoc-1.14.3/mandoc.3 0100644 0002007 0000011 00000035752 13141336265 0014016 0 ustar 00schwarze wsrc .\" $Id: mandoc.3,v 1.41 2017/07/04 23:40:01 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010-2017 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: July 4 2017 $
.Dt MANDOC 3
.Os
.Sh NAME
.Nm mandoc ,
.Nm deroff ,
.Nm mandocmsg ,
.Nm man_mparse ,
.Nm man_validate ,
.Nm mdoc_validate ,
.Nm mparse_alloc ,
.Nm mparse_free ,
.Nm mparse_getkeep ,
.Nm mparse_keep ,
.Nm mparse_open ,
.Nm mparse_readfd ,
.Nm mparse_reset ,
.Nm mparse_result ,
.Nm mparse_strerror ,
.Nm mparse_strlevel ,
.Nm mparse_updaterc
.Nd mandoc macro compiler library
.Sh SYNOPSIS
.In sys/types.h
.In mandoc.h
.Pp
.Fd "#define ASCII_NBRSP"
.Fd "#define ASCII_HYPH"
.Fd "#define ASCII_BREAK"
.Ft struct mparse *
.Fo mparse_alloc
.Fa "int options"
.Fa "enum mandocerr mmin"
.Fa "mandocmsg mmsg"
.Fa "enum mandoc_os oe_e"
.Fa "char *os_s"
.Fc
.Ft void
.Fo (*mandocmsg)
.Fa "enum mandocerr errtype"
.Fa "enum mandoclevel level"
.Fa "const char *file"
.Fa "int line"
.Fa "int col"
.Fa "const char *msg"
.Fc
.Ft void
.Fo mparse_free
.Fa "struct mparse *parse"
.Fc
.Ft const char *
.Fo mparse_getkeep
.Fa "const struct mparse *parse"
.Fc
.Ft void
.Fo mparse_keep
.Fa "struct mparse *parse"
.Fc
.Ft int
.Fo mparse_open
.Fa "struct mparse *parse"
.Fa "const char *fname"
.Fc
.Ft "enum mandoclevel"
.Fo mparse_readfd
.Fa "struct mparse *parse"
.Fa "int fd"
.Fa "const char *fname"
.Fc
.Ft void
.Fo mparse_reset
.Fa "struct mparse *parse"
.Fc
.Ft void
.Fo mparse_result
.Fa "struct mparse *parse"
.Fa "struct roff_man **man"
.Fa "char **sodest"
.Fc
.Ft "const char *"
.Fo mparse_strerror
.Fa "enum mandocerr"
.Fc
.Ft "const char *"
.Fo mparse_strlevel
.Fa "enum mandoclevel"
.Fc
.Ft void
.Fo mparse_updaterc
.Fa "struct mparse *parse"
.Fa "enum mandoclevel *rc"
.Fc
.In roff.h
.Ft void
.Fo deroff
.Fa "char **dest"
.Fa "const struct roff_node *node"
.Fc
.In sys/types.h
.In mandoc.h
.In mdoc.h
.Vt extern const char * const * mdoc_argnames;
.Vt extern const char * const * mdoc_macronames;
.Ft void
.Fo mdoc_validate
.Fa "struct roff_man *mdoc"
.Fc
.In sys/types.h
.In mandoc.h
.In man.h
.Vt extern const char * const * man_macronames;
.Ft "const struct mparse *"
.Fo man_mparse
.Fa "const struct roff_man *man"
.Fc
.Ft void
.Fo man_validate
.Fa "struct roff_man *man"
.Fc
.Sh DESCRIPTION
The
.Nm mandoc
library parses a
.Ux
manual into an abstract syntax tree (AST).
.Ux
manuals are composed of
.Xr mdoc 7
or
.Xr man 7 ,
and may be mixed with
.Xr roff 7 ,
.Xr tbl 7 ,
and
.Xr eqn 7
invocations.
.Pp
The following describes a general parse sequence:
.Bl -enum
.It
initiate a parsing sequence with
.Xr mchars_alloc 3
and
.Fn mparse_alloc ;
.It
open a file with
.Xr open 2
or
.Fn mparse_open ;
.It
parse it with
.Fn mparse_readfd ;
.It
close it with
.Xr close 2 ;
.It
retrieve the syntax tree with
.Fn mparse_result ;
.It
depending on whether the
.Fa macroset
member of the returned
.Vt struct roff_man
is
.Dv MACROSET_MDOC
or
.Dv MACROSET_MAN ,
validate it with
.Fn mdoc_validate
or
.Fn man_validate ,
respectively;
.It
if information about the validity of the input is needed, fetch it with
.Fn mparse_updaterc ;
.It
iterate over parse nodes with starting from the
.Fa first
member of the returned
.Vt struct roff_man ;
.It
free all allocated memory with
.Fn mparse_free
and
.Xr mchars_free 3 ,
or invoke
.Fn mparse_reset
and go back to step 2 to parse new files.
.El
.Sh REFERENCE
This section documents the functions, types, and variables available
via
.In mandoc.h ,
with the exception of those documented in
.Xr mandoc_escape 3
and
.Xr mchars_alloc 3 .
.Ss Types
.Bl -ohang
.It Vt "enum mandocerr"
An error or warning message during parsing.
.It Vt "enum mandoclevel"
A classification of an
.Vt "enum mandocerr"
as regards system operation.
See the DIAGNOSTICS section in
.Xr mandoc 1
regarding the meanings of the levels.
.It Vt "struct mparse"
An opaque pointer to a running parse sequence.
Created with
.Fn mparse_alloc
and freed with
.Fn mparse_free .
This may be used across parsed input if
.Fn mparse_reset
is called between parses.
.It Vt "mandocmsg"
A prototype for a function to handle error and warning
messages emitted by the parser.
.El
.Ss Functions
.Bl -ohang
.It Fn deroff
Obtain a text-only representation of a
.Vt struct roff_node ,
including text contained in its child nodes.
To be used on children of the
.Fa first
member of
.Vt struct roff_man .
When it is no longer needed, the pointer returned from
.Fn deroff
can be passed to
.Xr free 3 .
.It Fn man_mparse
Get the parser used for the current output.
Declared in
.In man.h ,
implemented in
.Pa man.c .
.It Fn man_validate
Validate the
.Dv MACROSET_MAN
parse tree obtained with
.Fn mparse_result .
Declared in
.In man.h ,
implemented in
.Pa man.c .
.It Fn mdoc_validate
Validate the
.Dv MACROSET_MDOC
parse tree obtained with
.Fn mparse_result .
Declared in
.In mdoc.h ,
implemented in
.Pa mdoc.c .
.It Fn mparse_alloc
Allocate a parser.
The arguments have the following effect:
.Bl -tag -offset 5n -width inttype
.It Ar options
When the
.Dv MPARSE_MDOC
or
.Dv MPARSE_MAN
bit is set, only that parser is used.
Otherwise, the document type is automatically detected.
.Pp
When the
.Dv MPARSE_SO
bit is set,
.Xr roff 7
.Ic \&so
file inclusion requests are always honoured.
Otherwise, if the request is the only content in an input file,
only the file name is remembered, to be returned in the
.Fa sodest
argument of
.Fn mparse_result .
.Pp
When the
.Dv MPARSE_QUICK
bit is set, parsing is aborted after the NAME section.
This is for example useful in
.Xr makewhatis 8
.Fl Q
to quickly build minimal databases.
.It Ar mmin
Can be set to
.Dv MANDOCERR_BASE ,
.Dv MANDOCERR_STYLE ,
.Dv MANDOCERR_WARNING ,
.Dv MANDOCERR_ERROR ,
.Dv MANDOCERR_UNSUPP ,
or
.Dv MANDOCERR_MAX .
Messages below the selected level will be suppressed.
.It Ar mmsg
A callback function to handle errors and warnings.
See
.Pa main.c
for an example.
If printing of error messages is not desired,
.Dv NULL
may be passed.
.It Ar os_e
Operating system to check base system conventions for.
If
.Dv MANDOC_OS_OTHER ,
the system is automatically detected from
.Ic \&Os ,
.Fl Ios ,
or
.Xr uname 3 .
.It Ar os_s
A default string for the
.Xr mdoc 7
.Ic \&Os
macro, overriding the
.Dv OSNAME
preprocessor definition and the results of
.Xr uname 3 .
Passing
.Dv NULL
sets no default.
.El
.Pp
The same parser may be used for multiple files so long as
.Fn mparse_reset
is called between parses.
.Fn mparse_free
must be called to free the memory allocated by this function.
Declared in
.In mandoc.h ,
implemented in
.Pa read.c .
.It Fn mparse_free
Free all memory allocated by
.Fn mparse_alloc .
Declared in
.In mandoc.h ,
implemented in
.Pa read.c .
.It Fn mparse_getkeep
Acquire the keep buffer.
Must follow a call of
.Fn mparse_keep .
Declared in
.In mandoc.h ,
implemented in
.Pa read.c .
.It Fn mparse_keep
Instruct the parser to retain a copy of its parsed input.
This can be acquired with subsequent
.Fn mparse_getkeep
calls.
Declared in
.In mandoc.h ,
implemented in
.Pa read.c .
.It Fn mparse_open
Open the file for reading.
If that fails and
.Fa fname
does not already end in
.Ql .gz ,
try again after appending
.Ql .gz .
Save the information whether the file is zipped or not.
Return a file descriptor open for reading or -1 on failure.
It can be passed to
.Fn mparse_readfd
or used directly.
Declared in
.In mandoc.h ,
implemented in
.Pa read.c .
.It Fn mparse_readfd
Parse a file descriptor opened with
.Xr open 2
or
.Fn mparse_open .
Pass the associated filename in
.Va fname .
This function may be called multiple times with different parameters; however,
.Xr close 2
and
.Fn mparse_reset
should be invoked between parses.
Declared in
.In mandoc.h ,
implemented in
.Pa read.c .
.It Fn mparse_reset
Reset a parser so that
.Fn mparse_readfd
may be used again.
Declared in
.In mandoc.h ,
implemented in
.Pa read.c .
.It Fn mparse_result
Obtain the result of a parse.
One of the two pointers will be filled in.
Declared in
.In mandoc.h ,
implemented in
.Pa read.c .
.It Fn mparse_strerror
Return a statically-allocated string representation of an error code.
Declared in
.In mandoc.h ,
implemented in
.Pa read.c .
.It Fn mparse_strlevel
Return a statically-allocated string representation of a level code.
Declared in
.In mandoc.h ,
implemented in
.Pa read.c .
.It Fn mparse_updaterc
If the highest warning or error level that occurred during the current
.Fa parse
is higher than
.Pf * Fa rc ,
update
.Pf * Fa rc
accordingly.
This is useful after calling
.Fn mdoc_validate
or
.Fn man_validate .
Declared in
.In mandoc.h ,
implemented in
.Pa read.c .
.El
.Ss Variables
.Bl -ohang
.It Va man_macronames
The string representation of a
.Xr man 7
macro as indexed by
.Vt "enum mant" .
.It Va mdoc_argnames
The string representation of an
.Xr mdoc 7
macro argument as indexed by
.Vt "enum mdocargt" .
.It Va mdoc_macronames
The string representation of an
.Xr mdoc 7
macro as indexed by
.Vt "enum mdoct" .
.El
.Sh IMPLEMENTATION NOTES
This section consists of structural documentation for
.Xr mdoc 7
and
.Xr man 7
syntax trees and strings.
.Ss Man and Mdoc Strings
Strings may be extracted from mdoc and man meta-data, or from text
nodes (MDOC_TEXT and MAN_TEXT, respectively).
These strings have special non-printing formatting cues embedded in the
text itself, as well as
.Xr roff 7
escapes preserved from input.
Implementing systems will need to handle both situations to produce
human-readable text.
In general, strings may be assumed to consist of 7-bit ASCII characters.
.Pp
The following non-printing characters may be embedded in text strings:
.Bl -tag -width Ds
.It Dv ASCII_NBRSP
A non-breaking space character.
.It Dv ASCII_HYPH
A soft hyphen.
.It Dv ASCII_BREAK
A breakable zero-width space.
.El
.Pp
Escape characters are also passed verbatim into text strings.
An escape character is a sequence of characters beginning with the
backslash
.Pq Sq \e .
To construct human-readable text, these should be intercepted with
.Xr mandoc_escape 3
and converted with one the functions described in
.Xr mchars_alloc 3 .
.Ss Man Abstract Syntax Tree
This AST is governed by the ontological rules dictated in
.Xr man 7
and derives its terminology accordingly.
.Pp
The AST is composed of
.Vt struct roff_node
nodes with element, root and text types as declared by the
.Va type
field.
Each node also provides its parse point (the
.Va line ,
.Va pos ,
and
.Va sec
fields), its position in the tree (the
.Va parent ,
.Va child ,
.Va next
and
.Va prev
fields) and some type-specific data.
.Pp
The tree itself is arranged according to the following normal form,
where capitalised non-terminals represent nodes.
.Pp
.Bl -tag -width "ELEMENTXX" -compact
.It ROOT
\(<- mnode+
.It mnode
\(<- ELEMENT | TEXT | BLOCK
.It BLOCK
\(<- HEAD BODY
.It HEAD
\(<- mnode*
.It BODY
\(<- mnode*
.It ELEMENT
\(<- ELEMENT | TEXT*
.It TEXT
\(<- [[:ascii:]]*
.El
.Pp
The only elements capable of nesting other elements are those with
next-line scope as documented in
.Xr man 7 .
.Ss Mdoc Abstract Syntax Tree
This AST is governed by the ontological
rules dictated in
.Xr mdoc 7
and derives its terminology accordingly.
.Qq In-line
elements described in
.Xr mdoc 7
are described simply as
.Qq elements .
.Pp
The AST is composed of
.Vt struct roff_node
nodes with block, head, body, element, root and text types as declared
by the
.Va type
field.
Each node also provides its parse point (the
.Va line ,
.Va pos ,
and
.Va sec
fields), its position in the tree (the
.Va parent ,
.Va child ,
.Va last ,
.Va next
and
.Va prev
fields) and some type-specific data, in particular, for nodes generated
from macros, the generating macro in the
.Va tok
field.
.Pp
The tree itself is arranged according to the following normal form,
where capitalised non-terminals represent nodes.
.Pp
.Bl -tag -width "ELEMENTXX" -compact
.It ROOT
\(<- mnode+
.It mnode
\(<- BLOCK | ELEMENT | TEXT
.It BLOCK
\(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]]
.It ELEMENT
\(<- TEXT*
.It HEAD
\(<- mnode*
.It BODY
\(<- mnode* [ENDBODY mnode*]
.It TAIL
\(<- mnode*
.It TEXT
\(<- [[:ascii:]]*
.El
.Pp
Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
the BLOCK production: these refer to punctuation marks.
Furthermore, although a TEXT node will generally have a non-zero-length
string, in the specific case of
.Sq \&.Bd \-literal ,
an empty line will produce a zero-length string.
Multiple body parts are only found in invocations of
.Sq \&Bl \-column ,
where a new body introduces a new phrase.
.Pp
The
.Xr mdoc 7
syntax tree accommodates for broken block structures as well.
The ENDBODY node is available to end the formatting associated
with a given block before the physical end of that block.
It has a non-null
.Va end
field, is of the BODY
.Va type ,
has the same
.Va tok
as the BLOCK it is ending, and has a
.Va pending
field pointing to that BLOCK's BODY node.
It is an indirect child of that BODY node
and has no children of its own.
.Pp
An ENDBODY node is generated when a block ends while one of its child
blocks is still open, like in the following example:
.Bd -literal -offset indent
\&.Ao ao
\&.Bo bo ac
\&.Ac bc
\&.Bc end
.Ed
.Pp
This example results in the following block structure:
.Bd -literal -offset indent
BLOCK Ao
HEAD Ao
BODY Ao
TEXT ao
BLOCK Bo, pending -> Ao
HEAD Bo
BODY Bo
TEXT bo
TEXT ac
ENDBODY Ao, pending -> Ao
TEXT bc
TEXT end
.Ed
.Pp
Here, the formatting of the
.Ic \&Ao
block extends from TEXT ao to TEXT ac,
while the formatting of the
.Ic \&Bo
block extends from TEXT bo to TEXT bc.
It renders as follows in
.Fl T Ns Cm ascii
mode:
.Pp
.Dl <ao [bo ac> bc] end
.Pp
Support for badly-nested blocks is only provided for backward
compatibility with some older
.Xr mdoc 7
implementations.
Using badly-nested blocks is
.Em strongly discouraged ;
for example, the
.Fl T Ns Cm html
front-end to
.Xr mandoc 1
is unable to render them in any meaningful way.
Furthermore, behaviour when encountering badly-nested blocks is not
consistent across troff implementations, especially when using multiple
levels of badly-nested blocks.
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr man.cgi 3 ,
.Xr mandoc_escape 3 ,
.Xr mandoc_headers 3 ,
.Xr mandoc_malloc 3 ,
.Xr mansearch 3 ,
.Xr mchars_alloc 3 ,
.Xr tbl 3 ,
.Xr eqn 7 ,
.Xr man 7 ,
.Xr mandoc_char 7 ,
.Xr mdoc 7 ,
.Xr roff 7 ,
.Xr tbl 7
.Sh AUTHORS
.An -nosplit
The
.Nm
library was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
and is maintained by
.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
mandoc-1.14.3/mandoc.css 0100644 0002007 0000011 00000010322 13141336265 0014426 0 ustar 00schwarze wsrc /* $Id: mandoc.css,v 1.22 2017/07/16 18:45:00 schwarze Exp $ */
/*
* Standard style sheet for mandoc(1) -Thtml and man.cgi(8).
*/
/* Global defaults. */
html { max-width: 100ex; }
body { font-family: Helvetica,Arial,sans-serif; }
table { margin-top: 0em;
margin-bottom: 0em; }
td { vertical-align: top; }
ul, ol, dl { margin-top: 0em;
margin-bottom: 0em; }
li, dt { margin-top: 1em; }
a.selflink { border-bottom: thin dotted;
color: inherit;
font: inherit;
text-decoration: inherit; }
* { clear: both }
/* Search form and search results. */
fieldset { border: thin solid silver;
border-radius: 1em;
text-align: center; }
input[name=expr] {
width: 25%; }
table.results { margin-top: 1em;
margin-left: 2em;
font-size: smaller; }
/* Header and footer lines. */
table.head { width: 100%;
border-bottom: 1px dotted #808080;
margin-bottom: 1em;
font-size: smaller; }
td.head-vol { text-align: center; }
td.head-rtitle {
text-align: right; }
span.Nd { }
table.foot { width: 100%;
border-top: 1px dotted #808080;
margin-top: 1em;
font-size: smaller; }
td.foot-os { text-align: right; }
/* Sections and paragraphs. */
div.manual-text {
margin-left: 5ex; }
h1.Sh { margin-top: 2ex;
margin-bottom: 1ex;
margin-left: -4ex;
font-size: 110%; }
h2.Ss { margin-top: 2ex;
margin-bottom: 1ex;
margin-left: -2ex;
font-size: 105%; }
div.Pp { margin: 1ex 0ex; }
a.Sx { }
a.Xr { }
/* Displays and lists. */
div.Bd { }
div.D1 { margin-left: 5ex; }
ul.Bl-bullet { list-style-type: disc;
padding-left: 1em; }
li.It-bullet { }
ul.Bl-dash { list-style-type: none;
padding-left: 0em; }
li.It-dash:before {
content: "\2014 "; }
ul.Bl-item { list-style-type: none;
padding-left: 0em; }
li.It-item { }
ul.Bl-compact > li {
margin-top: 0ex; }
ol.Bl-enum { padding-left: 2em; }
li.It-enum { }
ol.Bl-compact > li {
margin-top: 0ex; }
dl.Bl-diag { }
dt.It-diag { }
dd.It-diag { margin-left: 0ex; }
b.It-diag { font-style: normal; }
dl.Bl-hang { }
dt.It-hang { }
dd.It-hang { margin-left: 10.2ex; }
dl.Bl-inset { }
dt.It-inset { }
dd.It-inset { margin-left: 0ex; }
dl.Bl-ohang { }
dt.It-ohang { }
dd.It-ohang { margin-left: 0ex; }
dl.Bl-tag { margin-left: 10.2ex; }
dt.It-tag { float: left;
margin-top: 0ex;
margin-left: -10.2ex;
padding-right: 2ex;
vertical-align: top; }
dd.It-tag { clear: right;
width: 100%;
margin-top: 0ex;
margin-left: 0ex;
vertical-align: top;
overflow: auto; }
dl.Bl-compact > dt {
margin-top: 0ex; }
table.Bl-column { }
tr.It-column { }
td.It-column { margin-top: 1em; }
table.Bl-compact > tbody > tr > td {
margin-top: 0ex; }
cite.Rs { font-style: normal;
font-weight: normal; }
span.RsA { }
i.RsB { font-weight: normal; }
span.RsC { }
span.RsD { }
i.RsI { font-weight: normal; }
i.RsJ { font-weight: normal; }
span.RsN { }
span.RsO { }
span.RsP { }
span.RsQ { }
span.RsR { }
span.RsT { text-decoration: underline; }
a.RsU { }
span.RsV { }
span.eqn { }
table.tbl { }
/* Semantic markup for command line utilities. */
table.Nm { }
b.Nm { font-style: normal; }
b.Fl { font-style: normal; }
b.Cm { font-style: normal; }
var.Ar { font-style: italic;
font-weight: normal; }
span.Op { }
b.Ic { font-style: normal; }
code.Ev { font-style: normal;
font-weight: normal;
font-family: monospace; }
i.Pa { font-weight: normal; }
/* Semantic markup for function libraries. */
span.Lb { }
b.In { font-style: normal; }
a.In { }
b.Fd { font-style: normal; }
var.Ft { font-style: italic;
font-weight: normal; }
b.Fn { font-style: normal; }
var.Fa { font-style: italic;
font-weight: normal; }
var.Vt { font-style: italic;
font-weight: normal; }
var.Va { font-style: italic;
font-weight: normal; }
code.Dv { font-style: normal;
font-weight: normal;
font-family: monospace; }
code.Er { font-style: normal;
font-weight: normal;
font-family: monospace; }
/* Various semantic markup. */
span.An { }
a.Lk { }
a.Mt { }
b.Cd { font-style: normal; }
i.Ad { font-weight: normal; }
b.Ms { font-style: normal; }
span.St { }
a.Ux { }
/* Physical markup. */
.No { font-style: normal;
font-weight: normal; }
.Em { font-style: italic;
font-weight: normal; }
.Sy { font-style: normal;
font-weight: bold; }
.Li { font-style: normal;
font-weight: normal;
font-family: monospace; }
mandoc-1.14.3/mandoc.db.5 0100644 0002007 0000011 00000013362 13141336265 0014375 0 ustar 00schwarze wsrc .\" $Id: mandoc.db.5,v 1.5 2016/08/01 12:27:15 schwarze Exp $
.\"
.\" Copyright (c) 2014, 2016 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: August 1 2016 $
.Dt MANDOC.DB 5
.Os
.Sh NAME
.Nm mandoc.db
.Nd manual page database
.Sh DESCRIPTION
The
.Nm
file format is used to store information about installed manual
pages to facilitate semantic searching for manuals.
Each manual page tree contains its own
.Nm
file; see
.Sx FILES
for examples.
.Pp
Such database files are generated by
.Xr makewhatis 8
and used by
.Xr man 1 ,
.Xr apropos 1
and
.Xr whatis 1 .
.Pp
The file format uses three datatypes:
.Pp
.Bl -dash -compact -offset 2n -width 1n
.It
32-bit signed integer numbers in big endian (network) byte ordering
.It
NUL-terminated strings
.It
lists of NUL-terminated strings, terminated by a second NUL character
.El
.Pp
Numbers are aligned to four-byte boundaries; where they follow
strings or lists of strings, padding with additional NUL characters
occurs.
Some, but not all, numbers point to positions in the file.
These pointers are measured in bytes, and the first byte of the
file is considered to be byte 0.
.Pp
Each file consists of:
.Pp
.Bl -dash -compact -offset 2n -width 1n
.It
One magic number, 0x3a7d0cdb.
.It
One version number, currently 1.
.It
One pointer to the macros table.
.It
One pointer to the final magic number.
.It
The pages table (variable length).
.It
The macros table (variable length).
.It
The magic number once again, 0x3a7d0cdb.
.El
.Pp
The pages table contains one entry for each physical manual page
file, no matter how many hard and soft links it may have in the
file system.
The pages table consists of:
.Pp
.Bl -dash -compact -offset 2n -width 1n
.It
The number of pages in the database.
.It
For each page:
.Bl -dash -compact -offset 2n -width 1n
.It
One pointer to the list of names.
.It
One pointer to the list of sections.
.It
One pointer to the list of architectures
or 0 if the page is machine-independent.
.It
One pointer to the one-line description string.
.It
One pointer to the list of filenames.
.El
.It
For each page, the list of names.
Each name is preceded by a single byte indicating the sources of the name.
The meaning of the bits is:
.Bl -dash -compact -offset 2n -width 1n
.It
0x10: The name appears in a filename.
.It
0x08: The name appears in a header line, i.e. in a .Dt or .TH macro.
.It
0x04: The name is the first one in the title line, i.e. it appears
in the first .Nm macro in the NAME section.
.It
0x02: The name appears in any .Nm macro in the NAME section.
.It
0x01: The name appears in an .Nm block in the SYNOPSIS section.
.El
.It
For each page, the list of sections.
Each section is given as a string, not as a number.
.It
For each architecture-dependent page, the list of architectures.
.It
For each page, the one-line description string taken from the .Nd macro.
.It
For each page, the list of filenames relative to the root of the
respective manpath.
This list includes hard links, soft links, and links simulated
with .so
.Xr roff 7
requests.
The first filename is preceded by a single byte
having the following significance:
.Bl -dash -compact -offset 2n -width 1n
.It
.Dv FORM_SRC No = 0x01 :
The file format is
.Xr mdoc 7
or
.Xr man 7 .
.It
.Dv FORM_CAT No = 0x02 :
The manual page is preformatted.
.El
.It
Zero to three NUL bytes for padding.
.El
.Pp
The macros table consists of:
.Pp
.Bl -dash -compact -offset 2n -width 1n
.It
The number of different macro keys, currently 36.
The ordering of macros is defined in
.In mansearch.h
and the significance of the macro keys is documented in
.Xr apropos 1 .
.It
For each macro key, one pointer to the respective macro table.
.It
For each macro key, the macro table (variable length).
.El
.Pp
Each macro table consists of:
.Pp
.Bl -dash -compact -offset 2n -width 1n
.It
The number of entries in the table.
.It
For each entry:
.Bl -dash -compact -offset 2n -width 1n
.It
One pointer to the value of the macro key.
Each value is a string of text taken from some macro invocation.
.It
One pointer to the list of pages.
.El
.It
For each entry, the value of the macro key.
.It
Zero to three NUL bytes for padding.
.It
For each entry, one or more pointers to pages in the pages table,
pointing to the pointer to the list of names,
followed by the number 0.
.El
.Sh FILES
.Bl -tag -width /usr/share/man/mandoc.db -compact
.It Pa /usr/share/man/mandoc.db
The manual page database for the base system.
.It Pa /usr/X11R6/man/mandoc.db
The same for the
.Xr X 7
Window System.
.It Pa /usr/local/man/mandoc.db
The same for
.Xr packages 7 .
.El
.Pp
A program to dump
.Nm
files in a human-readable format suitable for
.Xr diff 1
is provided in the directory
.Pa /usr/src/regress/usr.bin/mandoc/db/dbm_dump/ .
.Sh SEE ALSO
.Xr apropos 1 ,
.Xr man 1 ,
.Xr whatis 1 ,
.Xr makewhatis 8
.Sh HISTORY
A manual page database
.Pa /usr/lib/whatis
first appeared in
.Bx 2 .
The present format first appeared in
.Ox 6.1 .
.Sh AUTHORS
.An -nosplit
The original version of
.Xr makewhatis 8
was written by
.An Bill Joy
in 1979.
The present database format was designed by
.An Ingo Schwarze Aq Mt schwarze@openbsd.org
in 2016.
mandoc-1.14.3/mandoc.h 0100644 0002007 0000011 00000044075 13141336265 0014101 0 ustar 00schwarze wsrc /* $Id: mandoc.h,v 1.245 2017/07/08 14:51:04 schwarze Exp $ */
/*
* Copyright (c) 2010, 2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
* Copyright (c) 2010-2017 Ingo Schwarze <schwarze@openbsd.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#define ASCII_NBRSP 31 /* non-breaking space */
#define ASCII_HYPH 30 /* breakable hyphen */
#define ASCII_BREAK 29 /* breakable zero-width space */
/*
* Status level. This refers to both internal status (i.e., whilst
* running, when warnings/errors are reported) and an indicator of a
* threshold of when to halt (when said internal state exceeds the
* threshold).
*/
enum mandoclevel {
MANDOCLEVEL_OK = 0,
MANDOCLEVEL_STYLE, /* style suggestions */
MANDOCLEVEL_WARNING, /* warnings: syntax, whitespace, etc. */
MANDOCLEVEL_ERROR, /* input has been thrown away */
MANDOCLEVEL_UNSUPP, /* input needs unimplemented features */
MANDOCLEVEL_BADARG, /* bad argument in invocation */
MANDOCLEVEL_SYSERR, /* system error */
MANDOCLEVEL_MAX
};
/*
* All possible things that can go wrong within a parse, be it libroff,
* libmdoc, or libman.
*/
enum mandocerr {
MANDOCERR_OK,
MANDOCERR_BASE, /* ===== start of base system conventions ===== */
MANDOCERR_MDOCDATE, /* Mdocdate found: Dd ... */
MANDOCERR_MDOCDATE_MISSING, /* Mdocdate missing: Dd ... */
MANDOCERR_ARCH_BAD, /* unknown architecture: Dt ... arch */
MANDOCERR_OS_ARG, /* operating system explicitly specified: Os ... */
MANDOCERR_RCS_MISSING, /* RCS id missing */
MANDOCERR_XR_BAD, /* referenced manual not found: Xr name sec */
MANDOCERR_STYLE, /* ===== start of style suggestions ===== */
MANDOCERR_DATE_LEGACY, /* legacy man(7) date format: Dd ... */
MANDOCERR_TITLE_CASE, /* lower case character in document title */
MANDOCERR_RCS_REP, /* duplicate RCS id: ... */
MANDOCERR_SEC_TYPO, /* typo in section name: Sh ... */
MANDOCERR_ARG_QUOTE, /* unterminated quoted argument */
MANDOCERR_MACRO_USELESS, /* useless macro: macro */
MANDOCERR_BX, /* consider using OS macro: macro */
MANDOCERR_ER_ORDER, /* errnos out of order: Er ... */
MANDOCERR_ER_REP, /* duplicate errno: Er ... */
MANDOCERR_DELIM, /* trailing delimiter: macro ... */
MANDOCERR_DELIM_NB, /* no blank before trailing delimiter: macro ... */
MANDOCERR_FI_SKIP, /* fill mode already enabled, skipping: fi */
MANDOCERR_NF_SKIP, /* fill mode already disabled, skipping: nf */
MANDOCERR_FUNC, /* function name without markup: name() */
MANDOCERR_SPACE_EOL, /* whitespace at end of input line */
MANDOCERR_COMMENT_BAD, /* bad comment style */
MANDOCERR_WARNING, /* ===== start of warnings ===== */
/* related to the prologue */
MANDOCERR_DT_NOTITLE, /* missing manual title, using UNTITLED: line */
MANDOCERR_TH_NOTITLE, /* missing manual title, using "": [macro] */
MANDOCERR_MSEC_MISSING, /* missing manual section, using "": macro */
MANDOCERR_MSEC_BAD, /* unknown manual section: Dt ... section */
MANDOCERR_DATE_MISSING, /* missing date, using today's date */
MANDOCERR_DATE_BAD, /* cannot parse date, using it verbatim: date */
MANDOCERR_DATE_FUTURE, /* date in the future, using it anyway: date */
MANDOCERR_OS_MISSING, /* missing Os macro, using "" */
MANDOCERR_PROLOG_LATE, /* late prologue macro: macro */
MANDOCERR_PROLOG_ORDER, /* prologue macros out of order: macros */
/* related to document structure */
MANDOCERR_SO, /* .so is fragile, better use ln(1): so path */
MANDOCERR_DOC_EMPTY, /* no document body */
MANDOCERR_SEC_BEFORE, /* content before first section header: macro */
MANDOCERR_NAMESEC_FIRST, /* first section is not NAME: Sh title */
MANDOCERR_NAMESEC_NONM, /* NAME section without Nm before Nd */
MANDOCERR_NAMESEC_NOND, /* NAME section without description */
MANDOCERR_NAMESEC_ND, /* description not at the end of NAME */
MANDOCERR_NAMESEC_BAD, /* bad NAME section content: macro */
MANDOCERR_NAMESEC_PUNCT, /* missing comma before name: Nm name */
MANDOCERR_ND_EMPTY, /* missing description line, using "" */
MANDOCERR_ND_LATE, /* description line outside NAME section */
MANDOCERR_SEC_ORDER, /* sections out of conventional order: Sh title */
MANDOCERR_SEC_REP, /* duplicate section title: Sh title */
MANDOCERR_SEC_MSEC, /* unexpected section: Sh title for ... only */
MANDOCERR_XR_SELF, /* cross reference to self: Xr name sec */
MANDOCERR_XR_ORDER, /* unusual Xr order: ... after ... */
MANDOCERR_XR_PUNCT, /* unusual Xr punctuation: ... after ... */
MANDOCERR_AN_MISSING, /* AUTHORS section without An macro */
/* related to macros and nesting */
MANDOCERR_MACRO_OBS, /* obsolete macro: macro */
MANDOCERR_MACRO_CALL, /* macro neither callable nor escaped: macro */
MANDOCERR_PAR_SKIP, /* skipping paragraph macro: macro ... */
MANDOCERR_PAR_MOVE, /* moving paragraph macro out of list: macro */
MANDOCERR_NS_SKIP, /* skipping no-space macro */
MANDOCERR_BLK_NEST, /* blocks badly nested: macro ... */
MANDOCERR_BD_NEST, /* nested displays are not portable: macro ... */
MANDOCERR_BL_MOVE, /* moving content out of list: macro */
MANDOCERR_TA_LINE, /* first macro on line: Ta */
MANDOCERR_BLK_LINE, /* line scope broken: macro breaks macro */
MANDOCERR_BLK_BLANK, /* skipping blank line in line scope */
/* related to missing arguments */
MANDOCERR_REQ_EMPTY, /* skipping empty request: request */
MANDOCERR_COND_EMPTY, /* conditional request controls empty scope */
MANDOCERR_MACRO_EMPTY, /* skipping empty macro: macro */
MANDOCERR_BLK_EMPTY, /* empty block: macro */
MANDOCERR_ARG_EMPTY, /* empty argument, using 0n: macro arg */
MANDOCERR_BD_NOTYPE, /* missing display type, using -ragged: Bd */
MANDOCERR_BL_LATETYPE, /* list type is not the first argument: Bl arg */
MANDOCERR_BL_NOWIDTH, /* missing -width in -tag list, using 6n */
MANDOCERR_EX_NONAME, /* missing utility name, using "": Ex */
MANDOCERR_FO_NOHEAD, /* missing function name, using "": Fo */
MANDOCERR_IT_NOHEAD, /* empty head in list item: Bl -type It */
MANDOCERR_IT_NOBODY, /* empty list item: Bl -type It */
MANDOCERR_IT_NOARG, /* missing argument, using next line: Bl -c It */
MANDOCERR_BF_NOFONT, /* missing font type, using \fR: Bf */
MANDOCERR_BF_BADFONT, /* unknown font type, using \fR: Bf font */
MANDOCERR_PF_SKIP, /* nothing follows prefix: Pf arg */
MANDOCERR_RS_EMPTY, /* empty reference block: Rs */
MANDOCERR_XR_NOSEC, /* missing section argument: Xr arg */
MANDOCERR_ARG_STD, /* missing -std argument, adding it: macro */
MANDOCERR_OP_EMPTY, /* missing option string, using "": OP */
MANDOCERR_UR_NOHEAD, /* missing resource identifier, using "": UR */
MANDOCERR_EQN_NOBOX, /* missing eqn box, using "": op */
/* related to bad arguments */
MANDOCERR_ARG_REP, /* duplicate argument: macro arg */
MANDOCERR_AN_REP, /* skipping duplicate argument: An -arg */
MANDOCERR_BD_REP, /* skipping duplicate display type: Bd -type */
MANDOCERR_BL_REP, /* skipping duplicate list type: Bl -type */
MANDOCERR_BL_SKIPW, /* skipping -width argument: Bl -type */
MANDOCERR_BL_COL, /* wrong number of cells */
MANDOCERR_AT_BAD, /* unknown AT&T UNIX version: At version */
MANDOCERR_FA_COMMA, /* comma in function argument: arg */
MANDOCERR_FN_PAREN, /* parenthesis in function name: arg */
MANDOCERR_LB_BAD, /* unknown library name: Lb ... */
MANDOCERR_RS_BAD, /* invalid content in Rs block: macro */
MANDOCERR_SM_BAD, /* invalid Boolean argument: macro arg */
MANDOCERR_FT_BAD, /* unknown font, skipping request: ft font */
MANDOCERR_TR_ODD, /* odd number of characters in request: tr char */
/* related to plain text */
MANDOCERR_FI_BLANK, /* blank line in fill mode, using .sp */
MANDOCERR_FI_TAB, /* tab in filled text */
MANDOCERR_EOS, /* new sentence, new line */
MANDOCERR_ESC_BAD, /* invalid escape sequence: esc */
MANDOCERR_STR_UNDEF, /* undefined string, using "": name */
/* related to tables */
MANDOCERR_TBLLAYOUT_SPAN, /* tbl line starts with span */
MANDOCERR_TBLLAYOUT_DOWN, /* tbl column starts with span */
MANDOCERR_TBLLAYOUT_VERT, /* skipping vertical bar in tbl layout */
MANDOCERR_ERROR, /* ===== start of errors ===== */
/* related to tables */
MANDOCERR_TBLOPT_ALPHA, /* non-alphabetic character in tbl options */
MANDOCERR_TBLOPT_BAD, /* skipping unknown tbl option: option */
MANDOCERR_TBLOPT_NOARG, /* missing tbl option argument: option */
MANDOCERR_TBLOPT_ARGSZ, /* wrong tbl option argument size: option */
MANDOCERR_TBLLAYOUT_NONE, /* empty tbl layout */
MANDOCERR_TBLLAYOUT_CHAR, /* invalid character in tbl layout: char */
MANDOCERR_TBLLAYOUT_PAR, /* unmatched parenthesis in tbl layout */
MANDOCERR_TBLDATA_NONE, /* tbl without any data cells */
MANDOCERR_TBLDATA_SPAN, /* ignoring data in spanned tbl cell: data */
MANDOCERR_TBLDATA_EXTRA, /* ignoring extra tbl data cells: data */
MANDOCERR_TBLDATA_BLK, /* data block open at end of tbl: macro */
/* related to document structure and macros */
MANDOCERR_FILE, /* cannot open file */
MANDOCERR_PROLOG_REP, /* duplicate prologue macro: macro */
MANDOCERR_DT_LATE, /* skipping late title macro: Dt args */
MANDOCERR_ROFFLOOP, /* input stack limit exceeded, infinite loop? */
MANDOCERR_CHAR_BAD, /* skipping bad character: number */
MANDOCERR_MACRO, /* skipping unknown macro: macro */
MANDOCERR_REQ_INSEC, /* skipping insecure request: request */
MANDOCERR_IT_STRAY, /* skipping item outside list: It ... */
MANDOCERR_TA_STRAY, /* skipping column outside column list: Ta */
MANDOCERR_BLK_NOTOPEN, /* skipping end of block that is not open */
MANDOCERR_RE_NOTOPEN, /* fewer RS blocks open, skipping: RE arg */
MANDOCERR_BLK_BROKEN, /* inserting missing end of block: macro ... */
MANDOCERR_BLK_NOEND, /* appending missing end of block: macro */
/* related to request and macro arguments */
MANDOCERR_NAMESC, /* escaped character not allowed in a name: name */
MANDOCERR_BD_FILE, /* NOT IMPLEMENTED: Bd -file */
MANDOCERR_BD_NOARG, /* skipping display without arguments: Bd */
MANDOCERR_BL_NOTYPE, /* missing list type, using -item: Bl */
MANDOCERR_CE_NONUM, /* argument is not numeric, using 1: ce ... */
MANDOCERR_NM_NONAME, /* missing manual name, using "": Nm */
MANDOCERR_OS_UNAME, /* uname(3) system call failed, using UNKNOWN */
MANDOCERR_ST_BAD, /* unknown standard specifier: St standard */
MANDOCERR_IT_NONUM, /* skipping request without numeric argument */
MANDOCERR_SO_PATH, /* NOT IMPLEMENTED: .so with absolute path or ".." */
MANDOCERR_SO_FAIL, /* .so request failed */
MANDOCERR_ARG_SKIP, /* skipping all arguments: macro args */
MANDOCERR_ARG_EXCESS, /* skipping excess arguments: macro ... args */
MANDOCERR_DIVZERO, /* divide by zero */
MANDOCERR_UNSUPP, /* ===== start of unsupported features ===== */
MANDOCERR_TOOLARGE, /* input too large */
MANDOCERR_CHAR_UNSUPP, /* unsupported control character: number */
MANDOCERR_REQ_UNSUPP, /* unsupported roff request: request */
MANDOCERR_TBLOPT_EQN, /* eqn delim option in tbl: arg */
MANDOCERR_TBLLAYOUT_MOD, /* unsupported tbl layout modifier: m */
MANDOCERR_TBLMACRO, /* ignoring macro in table: macro */
MANDOCERR_MAX
};
struct tbl_opts {
char tab; /* cell-separator */
char decimal; /* decimal point */
int opts;
#define TBL_OPT_CENTRE (1 << 0)
#define TBL_OPT_EXPAND (1 << 1)
#define TBL_OPT_BOX (1 << 2)
#define TBL_OPT_DBOX (1 << 3)
#define TBL_OPT_ALLBOX (1 << 4)
#define TBL_OPT_NOKEEP (1 << 5)
#define TBL_OPT_NOSPACE (1 << 6)
#define TBL_OPT_NOWARN (1 << 7)
int cols; /* number of columns */
int lvert; /* width of left vertical line */
int rvert; /* width of right vertical line */
};
enum tbl_cellt {
TBL_CELL_CENTRE, /* c, C */
TBL_CELL_RIGHT, /* r, R */
TBL_CELL_LEFT, /* l, L */
TBL_CELL_NUMBER, /* n, N */
TBL_CELL_SPAN, /* s, S */
TBL_CELL_LONG, /* a, A */
TBL_CELL_DOWN, /* ^ */
TBL_CELL_HORIZ, /* _, - */
TBL_CELL_DHORIZ, /* = */
TBL_CELL_MAX
};
/*
* A cell in a layout row.
*/
struct tbl_cell {
struct tbl_cell *next;
char *wstr; /* min width represented as a string */
size_t width; /* minimum column width */
size_t spacing; /* to the right of the column */
int vert; /* width of subsequent vertical line */
int col; /* column number, starting from 0 */
int flags;
#define TBL_CELL_TALIGN (1 << 0) /* t, T */
#define TBL_CELL_BALIGN (1 << 1) /* d, D */
#define TBL_CELL_BOLD (1 << 2) /* fB, B, b */
#define TBL_CELL_ITALIC (1 << 3) /* fI, I, i */
#define TBL_CELL_EQUAL (1 << 4) /* e, E */
#define TBL_CELL_UP (1 << 5) /* u, U */
#define TBL_CELL_WIGN (1 << 6) /* z, Z */
#define TBL_CELL_WMAX (1 << 7) /* x, X */
enum tbl_cellt pos;
};
/*
* A layout row.
*/
struct tbl_row {
struct tbl_row *next;
struct tbl_cell *first;
struct tbl_cell *last;
int vert; /* width of left vertical line */
};
enum tbl_datt {
TBL_DATA_NONE, /* has no data */
TBL_DATA_DATA, /* consists of data/string */
TBL_DATA_HORIZ, /* horizontal line */
TBL_DATA_DHORIZ, /* double-horizontal line */
TBL_DATA_NHORIZ, /* squeezed horizontal line */
TBL_DATA_NDHORIZ /* squeezed double-horizontal line */
};
/*
* A cell within a row of data. The "string" field contains the actual
* string value that's in the cell. The rest is layout.
*/
struct tbl_dat {
struct tbl_cell *layout; /* layout cell */
struct tbl_dat *next;
char *string; /* data (NULL if not TBL_DATA_DATA) */
int spans; /* how many spans follow */
int block; /* T{ text block T} */
enum tbl_datt pos;
};
enum tbl_spant {
TBL_SPAN_DATA, /* span consists of data */
TBL_SPAN_HORIZ, /* span is horizontal line */
TBL_SPAN_DHORIZ /* span is double horizontal line */
};
/*
* A row of data in a table.
*/
struct tbl_span {
struct tbl_opts *opts;
struct tbl_row *layout; /* layout row */
struct tbl_dat *first;
struct tbl_dat *last;
struct tbl_span *prev;
struct tbl_span *next;
int line; /* parse line */
enum tbl_spant pos;
};
enum eqn_boxt {
EQN_TEXT, /* text (number, variable, whatever) */
EQN_SUBEXPR, /* nested `eqn' subexpression */
EQN_LIST, /* list (braces, etc.) */
EQN_PILE, /* vertical pile */
EQN_MATRIX /* pile of piles */
};
enum eqn_fontt {
EQNFONT_NONE = 0,
EQNFONT_ROMAN,
EQNFONT_BOLD,
EQNFONT_FAT,
EQNFONT_ITALIC,
EQNFONT__MAX
};
enum eqn_post {
EQNPOS_NONE = 0,
EQNPOS_SUP,
EQNPOS_SUBSUP,
EQNPOS_SUB,
EQNPOS_TO,
EQNPOS_FROM,
EQNPOS_FROMTO,
EQNPOS_OVER,
EQNPOS_SQRT,
EQNPOS__MAX
};
enum eqn_pilet {
EQNPILE_NONE = 0,
EQNPILE_PILE,
EQNPILE_CPILE,
EQNPILE_RPILE,
EQNPILE_LPILE,
EQNPILE_COL,
EQNPILE_CCOL,
EQNPILE_RCOL,
EQNPILE_LCOL,
EQNPILE__MAX
};
/*
* A "box" is a parsed mathematical expression as defined by the eqn.7
* grammar.
*/
struct eqn_box {
int size; /* font size of expression */
#define EQN_DEFSIZE INT_MIN
enum eqn_boxt type; /* type of node */
struct eqn_box *first; /* first child node */
struct eqn_box *last; /* last child node */
struct eqn_box *next; /* node sibling */
struct eqn_box *prev; /* node sibling */
struct eqn_box *parent; /* node sibling */
char *text; /* text (or NULL) */
char *left; /* fence left-hand */
char *right; /* fence right-hand */
char *top; /* expression over-symbol */
char *bottom; /* expression under-symbol */
size_t args; /* arguments in parent */
size_t expectargs; /* max arguments in parent */
enum eqn_post pos; /* position of next box */
enum eqn_fontt font; /* font of box */
enum eqn_pilet pile; /* equation piling */
};
/*
* Parse options.
*/
#define MPARSE_MDOC 1 /* assume -mdoc */
#define MPARSE_MAN 2 /* assume -man */
#define MPARSE_SO 4 /* honour .so requests */
#define MPARSE_QUICK 8 /* abort the parse early */
#define MPARSE_UTF8 16 /* accept UTF-8 input */
#define MPARSE_LATIN1 32 /* accept ISO-LATIN-1 input */
enum mandoc_os {
MANDOC_OS_OTHER = 0,
MANDOC_OS_NETBSD,
MANDOC_OS_OPENBSD
};
enum mandoc_esc {
ESCAPE_ERROR = 0, /* bail! unparsable escape */
ESCAPE_IGNORE, /* escape to be ignored */
ESCAPE_SPECIAL, /* a regular special character */
ESCAPE_FONT, /* a generic font mode */
ESCAPE_FONTBOLD, /* bold font mode */
ESCAPE_FONTITALIC, /* italic font mode */
ESCAPE_FONTBI, /* bold italic font mode */
ESCAPE_FONTROMAN, /* roman font mode */
ESCAPE_FONTPREV, /* previous font mode */
ESCAPE_NUMBERED, /* a numbered glyph */
ESCAPE_UNICODE, /* a unicode codepoint */
ESCAPE_BREAK, /* break the output line */
ESCAPE_NOSPACE, /* suppress space if the last on a line */
ESCAPE_HORIZ, /* horizontal movement */
ESCAPE_HLINE, /* horizontal line drawing */
ESCAPE_SKIPCHAR, /* skip the next character */
ESCAPE_OVERSTRIKE /* overstrike all chars in the argument */
};
typedef void (*mandocmsg)(enum mandocerr, enum mandoclevel,
const char *, int, int, const char *);
struct mparse;
struct roff_man;
enum mandoc_esc mandoc_escape(const char **, const char **, int *);
void mchars_alloc(void);
void mchars_free(void);
int mchars_num2char(const char *, size_t);
const char *mchars_uc2str(int);
int mchars_num2uc(const char *, size_t);
int mchars_spec2cp(const char *, size_t);
const char *mchars_spec2str(const char *, size_t, size_t *);
struct mparse *mparse_alloc(int, enum mandocerr, mandocmsg,
enum mandoc_os, const char *);
void mparse_free(struct mparse *);
void mparse_keep(struct mparse *);
int mparse_open(struct mparse *, const char *);
enum mandoclevel mparse_readfd(struct mparse *, int, const char *);
enum mandoclevel mparse_readmem(struct mparse *, void *, size_t,
const char *);
void mparse_reset(struct mparse *);
void mparse_result(struct mparse *,
struct roff_man **, char **);
const char *mparse_getkeep(const struct mparse *);
const char *mparse_strerror(enum mandocerr);
const char *mparse_strlevel(enum mandoclevel);
void mparse_updaterc(struct mparse *, enum mandoclevel *);
mandoc-1.14.3/mandoc_aux.h 0100644 0002007 0000011 00000002475 13141336265 0014754 0 ustar 00schwarze wsrc /* $Id: mandoc_aux.h,v 1.7 2017/06/12 19:05:47 schwarze Exp $ */
/*
* Copyright (c) 2009, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
* Copyright (c) 2014, 2017 Ingo Schwarze <schwarze@openbsd.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
int mandoc_asprintf(char **, const char *, ...)
__attribute__((__format__ (__printf__, 2, 3)));
void *mandoc_calloc(size_t, size_t);
void *mandoc_malloc(size_t);
void *mandoc_realloc(void *, size_t);
void *mandoc_reallocarray(void *, size_t, size_t);
void *mandoc_recallocarray(void *, size_t, size_t, size_t);
char *mandoc_strdup(const char *);
char *mandoc_strndup(const char *, size_t);
mandoc-1.14.3/mandoc_char.7 0100644 0002007 0000011 00000070215 13141336266 0015011 0 ustar 00schwarze wsrc .\" $Id: mandoc_char.7,v 1.67 2017/06/14 20:57:07 schwarze Exp $
.\"
.\" Copyright (c) 2003 Jason McIntyre <jmc@openbsd.org>
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2011, 2013, 2015, 2017 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: June 14 2017 $
.Dt MANDOC_CHAR 7
.Os
.Sh NAME
.Nm mandoc_char
.Nd mandoc special characters
.Sh DESCRIPTION
This page documents the
.Xr roff 7
escape sequences accepted by
.Xr mandoc 1
to represent special characters in
.Xr mdoc 7
and
.Xr man 7
documents.
.Pp
The rendering depends on the
.Xr mandoc 1
output mode; in ASCII output, most characters are completely
unintelligible.
For that reason, using any of the special characters documented here,
except those discussed in the
.Sx DESCRIPTION ,
is strongly discouraged; they are supported merely for backwards
compatibility with existing documents.
.Pp
In particular, in English manual pages, do not use special-character
escape sequences to represent national language characters in author
names; instead, provide ASCII transcriptions of the names.
.Ss Dashes and Hyphens
In typography there are different types of dashes of various width:
the hyphen (-),
the minus sign (\(mi),
the en-dash (\(en),
and the em-dash (\(em).
.Pp
Hyphens are used for adjectives;
to separate the two parts of a compound word;
or to separate a word across two successive lines of text.
The hyphen does not need to be escaped:
.Bd -unfilled -offset indent
blue-eyed
lorry-driver
.Ed
.Pp
If a word on a text input line contains a hyphen, a formatter may decide
to insert an output line break after the hyphen if that helps filling
the current output line, but the whole word would overflow the line.
If it is important that the word is not broken across lines in this
way, a zero-width space
.Pq Sq \e&
can be inserted before or after the hyphen.
While
.Xr mandoc 1
never breaks the output line after hyphens adjacent to a zero-width
space, after any of the other dash- or hyphen-like characters
represented by escape sequences, or after hyphens inside words in
macro arguments, other software may not respect these rules and may
break the line even in such cases.
.Pp
Some
.Xr roff 7
implementations contains dictionaries allowing to break the line
at syllable boundaries even inside words that contain no hyphens.
Such automatic hyphenation is not supported by
.Xr mandoc 1 ,
which only breaks the line at whitespace, and inside words only
after existing hyphens.
.Pp
The mathematical minus sign is used for negative numbers or subtraction.
It should be written as
.Sq \e(mi :
.Bd -unfilled -offset indent
a = 3 \e(mi 1;
b = \e(mi2;
.Ed
.Pp
The en-dash is used to separate the two elements of a range,
or can be used the same way as an em-dash.
It should be written as
.Sq \e(en :
.Bd -unfilled -offset indent
pp. 95\e(en97.
Go away \e(en or else!
.Ed
.Pp
The em-dash can be used to show an interruption
or can be used the same way as colons, semi-colons, or parentheses.
It should be written as
.Sq \e(em :
.Bd -unfilled -offset indent
Three things \e(em apples, oranges, and bananas.
This is not that \e(em rather, this is that.
.Ed
.Pp
Note:
hyphens, minus signs, and en-dashes look identical under normal ASCII output.
Other formats, such as PostScript, render them correctly,
with differing widths.
.Ss Spaces
To separate words in normal text, for indenting and alignment
in literal context, and when none of the following special cases apply,
just use the normal space character
.Pq Sq \ .
.Pp
When filling text, output lines may be broken between words, i.e. at space
characters.
To prevent a line break between two particular words,
use the unpaddable non-breaking space escape sequence
.Pq Sq \e\ \&
instead of the normal space character.
For example, the input string
.Dq number\e\ 1
will be kept together as
.Dq number\ 1
on the same output line.
.Pp
On request and macro lines, the normal space character serves as an
argument delimiter.
To include whitespace into arguments, quoting is usually the best choice;
see the MACRO SYNTAX section in
.Xr roff 7 .
In some cases, using the non-breaking space escape sequence
.Pq Sq \e\ \&
may be preferable.
.Pp
To escape macro names and to protect whitespace at the end
of input lines, the zero-width space
.Pq Sq \e&
is often useful.
For example, in
.Xr mdoc 7 ,
a normal space character can be displayed in single quotes in either
of the following ways:
.Pp
.Dl .Sq \(dq \(dq
.Dl .Sq \e \e&
.Ss Quotes
On request and macro lines, the double-quote character
.Pq Sq \(dq
is handled specially to allow quoting.
One way to prevent this special handling is by using the
.Sq \e(dq
escape sequence.
.Pp
Note that on text lines, literal double-quote characters can be used
verbatim.
All other quote-like characters can be used verbatim as well,
even on request and macro lines.
.Ss Accents
In output modes supporting such special output characters, for example
.Fl T Cm pdf ,
and sometimes less consistently in
.Fl T Cm utf8 ,
some
.Xr roff 7
formatters convert the following ASCII input characters to the
following Unicode special output characters:
.Bl -column x(ga U+2018 -offset indent
.It \(ga Ta U+2018 Ta left single quotation mark
.It \(aq Ta U+2019 Ta right single quotation mark
.It \(ti Ta U+02DC Ta small tilde
.It \(ha Ta U+02C6 Ta modifier letter circumflex
.El
.Pp
In prose, this automatic substitution is often desirable;
but when these characters have to be displayed as plain ASCII
characters, for example in source code samples, they require
escaping to render as follows:
.Bl -column x(ga U+2018 -offset indent
.It \e(ga Ta U+0060 Ta grave accent
.It \e(aq Ta U+0027 Ta apostrophe
.It \e(ti Ta U+007E Ta tilde
.It \e(ha Ta U+005E Ta circumflex accent
.El
.Ss Periods
The period
.Pq Sq \&.
is handled specially at the beginning of an input line,
where it introduces a
.Xr roff 7
request or a macro, and when appearing alone as a macro argument in
.Xr mdoc 7 .
In such situations, prepend a zero-width space
.Pq Sq \e&.
to make it behave like normal text.
.Pp
Do not use the
.Sq \e.
escape sequence.
It does not prevent special handling of the period.
.Ss Backslashes
To include a literal backslash
.Pq Sq \e
into the output, use the
.Pq Sq \ee
escape sequence.
.Pp
Note that doubling it
.Pq Sq \e\e
is not the right way to output a backslash.
Because
.Xr mandoc 1
does not implement full
.Xr roff 7
functionality, it may work with
.Xr mandoc 1 ,
but it may have weird effects on complete
.Xr roff 7
implementations.
.Sh SPECIAL CHARACTERS
Special characters are encoded as
.Sq \eX
.Pq for a one-character escape ,
.Sq \e(XX
.Pq two-character ,
and
.Sq \e[N]
.Pq N-character .
For details, see the
.Em Special Characters
subsection of the
.Xr roff 7
manual.
.Pp
Spacing:
.Bl -column "Input" "Description" -offset indent -compact
.It Em Input Ta Em Description
.It Sq \e\ \& Ta unpaddable non-breaking space
.It \e\(ti Ta paddable non-breaking space
.It \e0 Ta unpaddable, breaking digit-width space
.It \e| Ta one-sixth \e(em narrow space, zero width in nroff mode
.It \e^ Ta one-twelfth \e(em half-narrow space, zero width in nroff
.It \e& Ta zero-width space
.It \e% Ta zero-width space allowing hyphenation
.El
.Pp
Lines:
.Bl -column "Input" "Rendered" "Description" -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(ba Ta \(ba Ta bar
.It \e(br Ta \(br Ta box rule
.It \e(ul Ta \(ul Ta underscore
.It \e(ru Ta \(ru Ta underscore (width 0.5m)
.It \e(rn Ta \(rn Ta overline
.It \e(bb Ta \(bb Ta broken bar
.It \e(sl Ta \(sl Ta forward slash
.It \e(rs Ta \(rs Ta backward slash
.El
.Pp
Text markers:
.Bl -column "Input" "Rendered" "Description" -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(ci Ta \(ci Ta circle
.It \e(bu Ta \(bu Ta bullet
.It \e(dd Ta \(dd Ta double dagger
.It \e(dg Ta \(dg Ta dagger
.It \e(lz Ta \(lz Ta lozenge
.It \e(sq Ta \(sq Ta white square
.It \e(ps Ta \(ps Ta paragraph
.It \e(sc Ta \(sc Ta section
.It \e(lh Ta \(lh Ta left hand
.It \e(rh Ta \(rh Ta right hand
.It \e(at Ta \(at Ta at
.It \e(sh Ta \(sh Ta hash (pound)
.It \e(CR Ta \(CR Ta carriage return
.It \e(OK Ta \(OK Ta check mark
.It \e(CL Ta \(CL Ta club suit
.It \e(SP Ta \(SP Ta spade suit
.It \e(HE Ta \(HE Ta heart suit
.It \e(DI Ta \(DI Ta diamond suit
.El
.Pp
Legal symbols:
.Bl -column "Input" "Rendered" "Description" -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(co Ta \(co Ta copyright
.It \e(rg Ta \(rg Ta registered
.It \e(tm Ta \(tm Ta trademarked
.El
.Pp
Punctuation:
.Bl -column "Input" "Rendered" "Description" -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(em Ta \(em Ta em-dash
.It \e(en Ta \(en Ta en-dash
.It \e(hy Ta \(hy Ta hyphen
.It \ee Ta \e Ta back-slash
.It \e. Ta \. Ta period
.It \e(r! Ta \(r! Ta upside-down exclamation
.It \e(r? Ta \(r? Ta upside-down question
.El
.Pp
Quotes:
.Bl -column "Input" "Rendered" "Description" -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(Bq Ta \(Bq Ta right low double-quote
.It \e(bq Ta \(bq Ta right low single-quote
.It \e(lq Ta \(lq Ta left double-quote
.It \e(rq Ta \(rq Ta right double-quote
.It \e(oq Ta \(oq Ta left single-quote
.It \e(cq Ta \(cq Ta right single-quote
.It \e(aq Ta \(aq Ta apostrophe quote (text)
.It \e(dq Ta \(dq Ta double quote (text)
.It \e(Fo Ta \(Fo Ta left guillemet
.It \e(Fc Ta \(Fc Ta right guillemet
.It \e(fo Ta \(fo Ta left single guillemet
.It \e(fc Ta \(fc Ta right single guillemet
.El
.Pp
Brackets:
.Bl -column "xxbracketrightbtx" Rendered Description -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(lB Ta \(lB Ta left bracket
.It \e(rB Ta \(rB Ta right bracket
.It \e(lC Ta \(lC Ta left brace
.It \e(rC Ta \(rC Ta right brace
.It \e(la Ta \(la Ta left angle
.It \e(ra Ta \(ra Ta right angle
.It \e(bv Ta \(bv Ta brace extension
.It \e[braceex] Ta \[braceex] Ta brace extension
.It \e[bracketlefttp] Ta \[bracketlefttp] Ta top-left hooked bracket
.It \e[bracketleftbt] Ta \[bracketleftbt] Ta bottom-left hooked bracket
.It \e[bracketleftex] Ta \[bracketleftex] Ta left hooked bracket extension
.It \e[bracketrighttp] Ta \[bracketrighttp] Ta top-right hooked bracket
.It \e[bracketrightbt] Ta \[bracketrightbt] Ta bottom-right hooked bracket
.It \e[bracketrightex] Ta \[bracketrightex] Ta right hooked bracket extension
.It \e(lt Ta \(lt Ta top-left hooked brace
.It \e[bracelefttp] Ta \[bracelefttp] Ta top-left hooked brace
.It \e(lk Ta \(lk Ta mid-left hooked brace
.It \e[braceleftmid] Ta \[braceleftmid] Ta mid-left hooked brace
.It \e(lb Ta \(lb Ta bottom-left hooked brace
.It \e[braceleftbt] Ta \[braceleftbt] Ta bottom-left hooked brace
.It \e[braceleftex] Ta \[braceleftex] Ta left hooked brace extension
.It \e(rt Ta \(rt Ta top-left hooked brace
.It \e[bracerighttp] Ta \[bracerighttp] Ta top-right hooked brace
.It \e(rk Ta \(rk Ta mid-right hooked brace
.It \e[bracerightmid] Ta \[bracerightmid] Ta mid-right hooked brace
.It \e(rb Ta \(rb Ta bottom-right hooked brace
.It \e[bracerightbt] Ta \[bracerightbt] Ta bottom-right hooked brace
.It \e[bracerightex] Ta \[bracerightex] Ta right hooked brace extension
.It \e[parenlefttp] Ta \[parenlefttp] Ta top-left hooked parenthesis
.It \e[parenleftbt] Ta \[parenleftbt] Ta bottom-left hooked parenthesis
.It \e[parenleftex] Ta \[parenleftex] Ta left hooked parenthesis extension
.It \e[parenrighttp] Ta \[parenrighttp] Ta top-right hooked parenthesis
.It \e[parenrightbt] Ta \[parenrightbt] Ta bottom-right hooked parenthesis
.It \e[parenrightex] Ta \[parenrightex] Ta right hooked parenthesis extension
.El
.Pp
Arrows:
.Bl -column "Input" "Rendered" "Description" -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(<- Ta \(<- Ta left arrow
.It \e(-> Ta \(-> Ta right arrow
.It \e(<> Ta \(<> Ta left-right arrow
.It \e(da Ta \(da Ta down arrow
.It \e(ua Ta \(ua Ta up arrow
.It \e(va Ta \(va Ta up-down arrow
.It \e(lA Ta \(lA Ta left double-arrow
.It \e(rA Ta \(rA Ta right double-arrow
.It \e(hA Ta \(hA Ta left-right double-arrow
.It \e(uA Ta \(uA Ta up double-arrow
.It \e(dA Ta \(dA Ta down double-arrow
.It \e(vA Ta \(vA Ta up-down double-arrow
.It \e(an Ta \(an Ta horizontal arrow extension
.El
.Pp
Logical:
.Bl -column "Input" "Rendered" "Description" -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(AN Ta \(AN Ta logical and
.It \e(OR Ta \(OR Ta logical or
.It \e(no Ta \(no Ta logical not
.It \e[tno] Ta \[tno] Ta logical not (text)
.It \e(te Ta \(te Ta existential quantifier
.It \e(fa Ta \(fa Ta universal quantifier
.It \e(st Ta \(st Ta such that
.It \e(tf Ta \(tf Ta therefore
.It \e(3d Ta \(3d Ta therefore
.It \e(or Ta \(or Ta bitwise or
.El
.Pp
Mathematical:
.Bl -column "xxcoproductxx" "Rendered" "Description" -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(pl Ta \(pl Ta plus
.It \e(mi Ta \(mi Ta minus
.It \e- Ta \- Ta minus (text)
.It \e(-+ Ta \(-+ Ta minus-plus
.It \e(+- Ta \(+- Ta plus-minus
.It \e[t+-] Ta \[t+-] Ta plus-minus (text)
.It \e(pc Ta \(pc Ta center-dot
.It \e(mu Ta \(mu Ta multiply
.It \e[tmu] Ta \[tmu] Ta multiply (text)
.It \e(c* Ta \(c* Ta circle-multiply
.It \e(c+ Ta \(c+ Ta circle-plus
.It \e(di Ta \(di Ta divide
.It \e[tdi] Ta \[tdi] Ta divide (text)
.It \e(f/ Ta \(f/ Ta fraction
.It \e(** Ta \(** Ta asterisk
.It \e(<= Ta \(<= Ta less-than-equal
.It \e(>= Ta \(>= Ta greater-than-equal
.It \e(<< Ta \(<< Ta much less
.It \e(>> Ta \(>> Ta much greater
.It \e(eq Ta \(eq Ta equal
.It \e(!= Ta \(!= Ta not equal
.It \e(== Ta \(== Ta equivalent
.It \e(ne Ta \(ne Ta not equivalent
.It \e(ap Ta \(ap Ta tilde operator
.It \e(|= Ta \(|= Ta asymptotically equal
.It \e(=\(ti Ta \(=~ Ta approximately equal
.It \e(\(ti\(ti Ta \(~~ Ta almost equal
.It \e(\(ti= Ta \(~= Ta almost equal
.It \e(pt Ta \(pt Ta proportionate
.It \e(es Ta \(es Ta empty set
.It \e(mo Ta \(mo Ta element
.It \e(nm Ta \(nm Ta not element
.It \e(sb Ta \(sb Ta proper subset
.It \e(nb Ta \(nb Ta not subset
.It \e(sp Ta \(sp Ta proper superset
.It \e(nc Ta \(nc Ta not superset
.It \e(ib Ta \(ib Ta reflexive subset
.It \e(ip Ta \(ip Ta reflexive superset
.It \e(ca Ta \(ca Ta intersection
.It \e(cu Ta \(cu Ta union
.It \e(/_ Ta \(/_ Ta angle
.It \e(pp Ta \(pp Ta perpendicular
.It \e(is Ta \(is Ta integral
.It \e[integral] Ta \[integral] Ta integral
.It \e[sum] Ta \[sum] Ta summation
.It \e[product] Ta \[product] Ta product
.It \e[coproduct] Ta \[coproduct] Ta coproduct
.It \e(gr Ta \(gr Ta gradient
.It \e(sr Ta \(sr Ta square root
.It \e[sqrt] Ta \[sqrt] Ta square root
.It \e(lc Ta \(lc Ta left-ceiling
.It \e(rc Ta \(rc Ta right-ceiling
.It \e(lf Ta \(lf Ta left-floor
.It \e(rf Ta \(rf Ta right-floor
.It \e(if Ta \(if Ta infinity
.It \e(Ah Ta \(Ah Ta aleph
.It \e(Im Ta \(Im Ta imaginary
.It \e(Re Ta \(Re Ta real
.It \e(wp Ta \(wp Ta Weierstrass p
.It \e(pd Ta \(pd Ta partial differential
.It \e(-h Ta \(-h Ta Planck constant over 2\(*p
.It \e[hbar] Ta \[hbar] Ta Planck constant over 2\(*p
.It \e(12 Ta \(12 Ta one-half
.It \e(14 Ta \(14 Ta one-fourth
.It \e(34 Ta \(34 Ta three-fourths
.It \e(18 Ta \(18 Ta one-eighth
.It \e(38 Ta \(38 Ta three-eighths
.It \e(58 Ta \(58 Ta five-eighths
.It \e(78 Ta \(78 Ta seven-eighths
.It \e(S1 Ta \(S1 Ta superscript 1
.It \e(S2 Ta \(S2 Ta superscript 2
.It \e(S3 Ta \(S3 Ta superscript 3
.El
.Pp
Ligatures:
.Bl -column "Input" "Rendered" "Description" -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(ff Ta \(ff Ta ff ligature
.It \e(fi Ta \(fi Ta fi ligature
.It \e(fl Ta \(fl Ta fl ligature
.It \e(Fi Ta \(Fi Ta ffi ligature
.It \e(Fl Ta \(Fl Ta ffl ligature
.It \e(AE Ta \(AE Ta AE
.It \e(ae Ta \(ae Ta ae
.It \e(OE Ta \(OE Ta OE
.It \e(oe Ta \(oe Ta oe
.It \e(ss Ta \(ss Ta German eszett
.It \e(IJ Ta \(IJ Ta IJ ligature
.It \e(ij Ta \(ij Ta ij ligature
.El
.Pp
Accents:
.Bl -column "Input" "Rendered" "Description" -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(a" Ta \(a" Ta Hungarian umlaut
.It \e(a- Ta \(a- Ta macron
.It \e(a. Ta \(a. Ta dotted
.It \e(a^ Ta \(a^ Ta circumflex
.It \e(aa Ta \(aa Ta acute
.It \e\(aq Ta \' Ta acute
.It \e(ga Ta \(ga Ta grave
.It \e\(ga Ta \` Ta grave
.It \e(ab Ta \(ab Ta breve
.It \e(ac Ta \(ac Ta cedilla
.It \e(ad Ta \(ad Ta dieresis
.It \e(ah Ta \(ah Ta caron
.It \e(ao Ta \(ao Ta ring
.It \e(a\(ti Ta \(a~ Ta tilde
.It \e(ho Ta \(ho Ta ogonek
.It \e(ha Ta \(ha Ta hat (text)
.It \e(ti Ta \(ti Ta tilde (text)
.El
.Pp
Accented letters:
.Bl -column "Input" "Rendered" "Description" -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(\(aqA Ta \('A Ta acute A
.It \e(\(aqE Ta \('E Ta acute E
.It \e(\(aqI Ta \('I Ta acute I
.It \e(\(aqO Ta \('O Ta acute O
.It \e(\(aqU Ta \('U Ta acute U
.It \e(\(aqa Ta \('a Ta acute a
.It \e(\(aqe Ta \('e Ta acute e
.It \e(\(aqi Ta \('i Ta acute i
.It \e(\(aqo Ta \('o Ta acute o
.It \e(\(aqu Ta \('u Ta acute u
.It \e(\(gaA Ta \(`A Ta grave A
.It \e(\(gaE Ta \(`E Ta grave E
.It \e(\(gaI Ta \(`I Ta grave I
.It \e(\(gaO Ta \(`O Ta grave O
.It \e(\(gaU Ta \(`U Ta grave U
.It \e(\(gaa Ta \(`a Ta grave a
.It \e(\(gae Ta \(`e Ta grave e
.It \e(\(gai Ta \(`i Ta grave i
.It \e(\(gao Ta \(`i Ta grave o
.It \e(\(gau Ta \(`u Ta grave u
.It \e(\(tiA Ta \(~A Ta tilde A
.It \e(\(tiN Ta \(~N Ta tilde N
.It \e(\(tiO Ta \(~O Ta tilde O
.It \e(\(tia Ta \(~a Ta tilde a
.It \e(\(tin Ta \(~n Ta tilde n
.It \e(\(tio Ta \(~o Ta tilde o
.It \e(:A Ta \(:A Ta dieresis A
.It \e(:E Ta \(:E Ta dieresis E
.It \e(:I Ta \(:I Ta dieresis I
.It \e(:O Ta \(:O Ta dieresis O
.It \e(:U Ta \(:U Ta dieresis U
.It \e(:a Ta \(:a Ta dieresis a
.It \e(:e Ta \(:e Ta dieresis e
.It \e(:i Ta \(:i Ta dieresis i
.It \e(:o Ta \(:o Ta dieresis o
.It \e(:u Ta \(:u Ta dieresis u
.It \e(:y Ta \(:y Ta dieresis y
.It \e(^A Ta \(^A Ta circumflex A
.It \e(^E Ta \(^E Ta circumflex E
.It \e(^I Ta \(^I Ta circumflex I
.It \e(^O Ta \(^O Ta circumflex O
.It \e(^U Ta \(^U Ta circumflex U
.It \e(^a Ta \(^a Ta circumflex a
.It \e(^e Ta \(^e Ta circumflex e
.It \e(^i Ta \(^i Ta circumflex i
.It \e(^o Ta \(^o Ta circumflex o
.It \e(^u Ta \(^u Ta circumflex u
.It \e(,C Ta \(,C Ta cedilla C
.It \e(,c Ta \(,c Ta cedilla c
.It \e(/L Ta \(/L Ta stroke L
.It \e(/l Ta \(/l Ta stroke l
.It \e(/O Ta \(/O Ta stroke O
.It \e(/o Ta \(/o Ta stroke o
.It \e(oA Ta \(oA Ta ring A
.It \e(oa Ta \(oa Ta ring a
.El
.Pp
Special letters:
.Bl -column "Input" "Rendered" "Description" -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(-D Ta \(-D Ta Eth
.It \e(Sd Ta \(Sd Ta eth
.It \e(TP Ta \(TP Ta Thorn
.It \e(Tp Ta \(Tp Ta thorn
.It \e(.i Ta \(.i Ta dotless i
.It \e(.j Ta \(.j Ta dotless j
.El
.Pp
Currency:
.Bl -column "Input" "Rendered" "Description" -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(Do Ta \(Do Ta dollar
.It \e(ct Ta \(ct Ta cent
.It \e(Eu Ta \(Eu Ta Euro symbol
.It \e(eu Ta \(eu Ta Euro symbol
.It \e(Ye Ta \(Ye Ta yen
.It \e(Po Ta \(Po Ta pound
.It \e(Cs Ta \(Cs Ta Scandinavian
.It \e(Fn Ta \(Fn Ta florin
.El
.Pp
Units:
.Bl -column "Input" "Rendered" "Description" -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(de Ta \(de Ta degree
.It \e(%0 Ta \(%0 Ta per-thousand
.It \e(fm Ta \(fm Ta minute
.It \e(sd Ta \(sd Ta second
.It \e(mc Ta \(mc Ta micro
.It \e(Of Ta \(Of Ta Spanish female ordinal
.It \e(Om Ta \(Om Ta Spanish masculine ordinal
.El
.Pp
Greek letters:
.Bl -column "Input" "Rendered" "Description" -offset indent -compact
.It Em Input Ta Em Rendered Ta Em Description
.It \e(*A Ta \(*A Ta Alpha
.It \e(*B Ta \(*B Ta Beta
.It \e(*G Ta \(*G Ta Gamma
.It \e(*D Ta \(*D Ta Delta
.It \e(*E Ta \(*E Ta Epsilon
.It \e(*Z Ta \(*Z Ta Zeta
.It \e(*Y Ta \(*Y Ta Eta
.It \e(*H Ta \(*H Ta Theta
.It \e(*I Ta \(*I Ta Iota
.It \e(*K Ta \(*K Ta Kappa
.It \e(*L Ta \(*L Ta Lambda
.It \e(*M Ta \(*M Ta Mu
.It \e(*N Ta \(*N Ta Nu
.It \e(*C Ta \(*C Ta Xi
.It \e(*O Ta \(*O Ta Omicron
.It \e(*P Ta \(*P Ta Pi
.It \e(*R Ta \(*R Ta Rho
.It \e(*S Ta \(*S Ta Sigma
.It \e(*T Ta \(*T Ta Tau
.It \e(*U Ta \(*U Ta Upsilon
.It \e(*F Ta \(*F Ta Phi
.It \e(*X Ta \(*X Ta Chi
.It \e(*Q Ta \(*Q Ta Psi
.It \e(*W Ta \(*W Ta Omega
.It \e(*a Ta \(*a Ta alpha
.It \e(*b Ta \(*b Ta beta
.It \e(*g Ta \(*g Ta gamma
.It \e(*d Ta \(*d Ta delta
.It \e(*e Ta \(*e Ta epsilon
.It \e(*z Ta \(*z Ta zeta
.It \e(*y Ta \(*y Ta eta
.It \e(*h Ta \(*h Ta theta
.It \e(*i Ta \(*i Ta iota
.It \e(*k Ta \(*k Ta kappa
.It \e(*l Ta \(*l Ta lambda
.It \e(*m Ta \(*m Ta mu
.It \e(*n Ta \(*n Ta nu
.It \e(*c Ta \(*c Ta xi
.It \e(*o Ta \(*o Ta omicron
.It \e(*p Ta \(*p Ta pi
.It \e(*r Ta \(*r Ta rho
.It \e(*s Ta \(*s Ta sigma
.It \e(*t Ta \(*t Ta tau
.It \e(*u Ta \(*u Ta upsilon
.It \e(*f Ta \(*f Ta phi
.It \e(*x Ta \(*x Ta chi
.It \e(*q Ta \(*q Ta psi
.It \e(*w Ta \(*w Ta omega
.It \e(+h Ta \(+h Ta theta variant
.It \e(+f Ta \(+f Ta phi variant
.It \e(+p Ta \(+p Ta pi variant
.It \e(+e Ta \(+e Ta epsilon variant
.It \e(ts Ta \(ts Ta sigma terminal
.El
.Sh PREDEFINED STRINGS
Predefined strings are inherited from the macro packages of historical
troff implementations.
They are
.Em not recommended
for use, as they differ across implementations.
Manuals using these predefined strings are almost certainly not
portable.
.Pp
Their syntax is similar to special characters, using
.Sq \e*X
.Pq for a one-character escape ,
.Sq \e*(XX
.Pq two-character ,
and
.Sq \e*[N]
.Pq N-character .
For details, see the
.Em Predefined Strings
subsection of the
.Xr roff 7
manual.
.Bl -column "Input" "Rendered" "Description" -offset indent
.It Em Input Ta Em Rendered Ta Em Description
.It \e*(Ba Ta \*(Ba Ta vertical bar
.It \e*(Ne Ta \*(Ne Ta not equal
.It \e*(Ge Ta \*(Ge Ta greater-than-equal
.It \e*(Le Ta \*(Le Ta less-than-equal
.It \e*(Gt Ta \*(Gt Ta greater-than
.It \e*(Lt Ta \*(Lt Ta less-than
.It \e*(Pm Ta \*(Pm Ta plus-minus
.It \e*(If Ta \*(If Ta infinity
.It \e*(Pi Ta \*(Pi Ta pi
.It \e*(Na Ta \*(Na Ta NaN
.It \e*(Am Ta \*(Am Ta ampersand
.It \e*R Ta \*R Ta restricted mark
.It \e*(Tm Ta \*(Tm Ta trade mark
.It \e*q Ta \*q Ta double-quote
.It \e*(Rq Ta \*(Rq Ta right-double-quote
.It \e*(Lq Ta \*(Lq Ta left-double-quote
.It \e*(lp Ta \*(lp Ta right-parenthesis
.It \e*(rp Ta \*(rp Ta left-parenthesis
.It \e*(lq Ta \*(lq Ta left double-quote
.It \e*(rq Ta \*(rq Ta right double-quote
.It \e*(ua Ta \*(ua Ta up arrow
.It \e*(va Ta \*(va Ta up-down arrow
.It \e*(<= Ta \*(<= Ta less-than-equal
.It \e*(>= Ta \*(>= Ta greater-than-equal
.It \e*(aa Ta \*(aa Ta acute
.It \e*(ga Ta \*(ga Ta grave
.It \e*(Px Ta \*(Px Ta POSIX standard name
.It \e*(Ai Ta \*(Ai Ta ANSI standard name
.El
.Sh UNICODE CHARACTERS
The escape sequences
.Pp
.Dl \e[uXXXX] and \eC\(aquXXXX\(aq
.Pp
are interpreted as Unicode codepoints.
The codepoint must be in the range above U+0080 and less than U+10FFFF.
For compatibility, the hexadecimal digits
.Sq A
to
.Sq F
must be given as uppercase characters,
and points must be zero-padded to four characters; if
greater than four characters, no zero padding is allowed.
Unicode surrogates are not allowed.
.Sh NUMBERED CHARACTERS
For backward compatibility with existing manuals,
.Xr mandoc 1
also supports the
.Pp
.Dl \eN\(aq Ns Ar number Ns \(aq
.Pp
escape sequence, inserting the character
.Ar number
from the current character set into the output.
Of course, this is inherently non-portable and is already marked
as deprecated in the Heirloom roff manual.
For example, do not use \eN\(aq34\(aq, use \e(dq, or even the plain
.Sq \(dq
character where possible.
.Sh COMPATIBILITY
This section documents compatibility between mandoc and other
troff implementations, at this time limited to GNU troff
.Pq Qq groff .
.Pp
.Bl -dash -compact
.It
The \eN\(aq\(aq escape sequence is limited to printable characters; in
groff, it accepts arbitrary character numbers.
.It
In
.Fl T Ns Cm ascii ,
the
\e(ss, \e(nm, \e(nb, \e(nc, \e(ib, \e(ip, \e(pp, \e[sum], \e[product],
\e[coproduct], \e(gr, \e(-h, and \e(a. special characters render
differently between mandoc and groff.
.It
In
.Fl T Ns Cm html ,
the \e(\(ti=, \e(nb, and \e(nc special characters render differently
between mandoc and groff.
.It
The
.Fl T Ns Cm ps
and
.Fl T Ns Cm pdf
modes format like
.Fl T Ns Cm ascii
instead of rendering glyphs as in groff.
.It
The \e[radicalex], \e[sqrtex], and \e(ru special characters have been omitted
from mandoc either because they are poorly documented or they have no
known representation.
.El
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr man 7 ,
.Xr mdoc 7 ,
.Xr roff 7
.Sh AUTHORS
The
.Nm
manual page was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
.Sh CAVEATS
The predefined string
.Sq \e*(Ba
mimics the behaviour of the
.Sq \&|
character in
.Xr mdoc 7 ;
thus, if you wish to render a vertical bar with no side effects, use
the
.Sq \e(ba
escape.
mandoc-1.14.3/mandoc_escape.3 0100644 0002007 0000011 00000022516 13141336266 0015331 0 ustar 00schwarze wsrc .\" $Id: mandoc_escape.3,v 1.4 2017/07/04 23:40:01 schwarze Exp $
.\"
.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: July 4 2017 $
.Dt MANDOC_ESCAPE 3
.Os
.Sh NAME
.Nm mandoc_escape
.Nd parse roff escape sequences
.Sh SYNOPSIS
.In sys/types.h
.In mandoc.h
.Ft "enum mandoc_esc"
.Fo mandoc_escape
.Fa "const char **end"
.Fa "const char **start"
.Fa "int *sz"
.Fc
.Sh DESCRIPTION
This function scans a
.Xr roff 7
escape sequence.
.Pp
An escape sequence consists of
.Bl -dash -compact -width 2n
.It
an initial backslash character
.Pq Sq \e ,
.It
a single ASCII character called the escape sequence identifier,
.It
and, with only a few exceptions, an argument.
.El
.Pp
Arguments can be given in the following forms; some escape sequence
identifiers only accept some of these forms as specified below.
The first three forms are called the standard forms.
.Bl -tag -width 2n
.It \&In brackets: Ic \&[ Ns Ar argument Ns Ic \&]
The argument starts after the initial
.Sq \&[ ,
ends before the final
.Sq \&] ,
and the escape sequence ends with the final
.Sq \&] .
.It Two-character argument short form: Ic \&( Ns Ar ar
This form can only be used for arguments
consisting of exactly two characters.
It has the same effect as
.Ic \&[ Ns Ar ar Ns Ic \&] .
.It One-character argument short form: Ar a
This form can only be used for arguments
consisting of exactly one character.
It has the same effect as
.Ic \&[ Ns Ar a Ns Ic \&] .
.It Delimited form: Ar C Ns Ar argument Ns Ar C
The argument starts after the initial delimiter character
.Ar C ,
ends before the next occurrence of the delimiter character
.Ar C ,
and the escape sequence ends with that second
.Ar C .
Some escape sequences allow arbitrary characters
.Ar C
as quoting characters, some restrict the range of characters
that can be used as quoting characters.
.El
.Pp
Upon function entry,
.Fa end
is expected to point to the escape sequence identifier.
The values passed in as
.Fa start
and
.Fa sz
are ignored and overwritten.
.Pp
By design, this function cannot handle those
.Xr roff 7
escape sequences that require in-place expansion, in particular
user-defined strings
.Ic \e* ,
number registers
.Ic \en ,
width measurements
.Ic \ew ,
and numerical expression control
.Ic \eB .
These are handled by
.Fn roff_res ,
a private preprocessor function called from
.Fn roff_parseln ,
see the file
.Pa roff.c .
.Pp
The function
.Fn mandoc_escape
is used
.Bl -dash -compact -width 2n
.It
recursively by itself, because some escape sequence arguments can
in turn contain other escape sequences,
.It
for error detection internally by the
.Xr roff 7
parser part of the
.Xr mandoc 3
library, see the file
.Pa roff.c ,
.It
above all externally by the
.Xr mandoc 1
formatting modules, in particular
.Fl Tascii
and
.Fl Thtml ,
for formatting purposes, see the files
.Pa term.c
and
.Pa html.c ,
.It
and rarely externally by high-level utilities using the mandoc library,
for example
.Xr makewhatis 8 ,
to purge escape sequences from text.
.El
.Sh RETURN VALUES
Upon function return, the pointer
.Fa end
is set to the character after the end of the escape sequence,
such that the calling higher-level parser can easily continue.
.Pp
For escape sequences taking an argument, the pointer
.Fa start
is set to the beginning of the argument and
.Fa sz
is set to the length of the argument.
For escape sequences not taking an argument,
.Fa start
is set to the character after the end of the sequence and
.Fa sz
is set to 0.
Both
.Fa start
and
.Fa sz
may be
.Dv NULL ;
in that case, the argument and the length are not returned.
.Pp
For sequences taking an argument, the function
.Fn mandoc_escape
returns one of the following values:
.Bl -tag -width 2n
.It Dv ESCAPE_FONT
The escape sequence
.Ic \ef
taking an argument in standard form:
.Ic \ef[ , \ef( , \ef Ns Ar a .
Two-character arguments starting with the character
.Sq C
are reduced to one-character arguments by skipping the
.Sq C .
More specific values are returned for the most commonly used arguments:
.Bl -column "argument" "ESCAPE_FONTITALIC"
.It argument Ta return value
.It Cm R No or Cm 1 Ta Dv ESCAPE_FONTROMAN
.It Cm I No or Cm 2 Ta Dv ESCAPE_FONTITALIC
.It Cm B No or Cm 3 Ta Dv ESCAPE_FONTBOLD
.It Cm P Ta Dv ESCAPE_FONTPREV
.It Cm BI Ta Dv ESCAPE_FONTBI
.El
.It Dv ESCAPE_SPECIAL
The escape sequence
.Ic \eC
taking an argument delimited with the single quote character
and, as a special exception, the escape sequences
.Em not
having an identifier, that is, those where the argument, in standard
form, directly follows the initial backslash:
.Ic \eC' , \e[ , \e( , \e Ns Ar a .
Note that the one-character argument short form can only be used for
argument characters that do not clash with escape sequence identifiers.
.Pp
If the argument matches one of the forms described below under
.Dv ESCAPE_UNICODE ,
that value is returned instead.
.Pp
The
.Dv ESCAPE_SPECIAL
special character escape sequences can be rendered using the functions
.Fn mchars_spec2cp
and
.Fn mchars_spec2str
described in the
.Xr mchars_alloc 3
manual.
.It Dv ESCAPE_UNICODE
Escape sequences of the same format as described above under
.Dv ESCAPE_SPECIAL ,
but with an argument of the forms
.Ic u Ns Ar XXXX ,
.Ic u Ns Ar YXXXX ,
or
.Ic u10 Ns Ar XXXX
where
.Ar X
and
.Ar Y
are hexadecimal digits and
.Ar Y
is not zero:
.Ic \eC'u , \e[u .
As a special exception,
.Fa start
is set to the character after the
.Ic u ,
and the
.Fa sz
return value does not include the
.Ic u
either.
.Pp
Such Unicode character escape sequences can be rendered using the function
.Fn mchars_num2uc
described in the
.Xr mchars_alloc 3
manual.
.It Dv ESCAPE_NUMBERED
The escape sequence
.Ic \eN
followed by a delimited argument.
The delimiter character is arbitrary except that digits cannot be used.
If a digit is encountered instead of the opening delimiter, that
digit is considered to be the argument and the end of the sequence, and
.Dv ESCAPE_IGNORE
is returned.
.Pp
Such ASCII character escape sequences can be rendered using the function
.Fn mchars_num2char
described in the
.Xr mchars_alloc 3
manual.
.It Dv ESCAPE_OVERSTRIKE
The escape sequence
.Ic \eo
followed by an argument delimited by an arbitrary character.
.It Dv ESCAPE_IGNORE
.Bl -bullet -width 2n
.It
The escape sequence
.Ic \es
followed by an argument in standard form or by an argument delimited
by the single quote character:
.Ic \es' , \es[ , \es( , \es Ns Ar a .
As a special exception, an optional
.Sq +
or
.Sq \-
character is allowed after the
.Sq s
for all forms.
.It
The escape sequences
.Ic \eF ,
.Ic \eg ,
.Ic \ek ,
.Ic \eM ,
.Ic \em ,
.Ic \en ,
.Ic \eV ,
and
.Ic \eY
followed by an argument in standard form.
.It
The escape sequences
.Ic \eA ,
.Ic \eb ,
.Ic \eD ,
.Ic \eR ,
.Ic \eX ,
and
.Ic \eZ
followed by an argument delimited by an arbitrary character.
.It
The escape sequences
.Ic \eH ,
.Ic \eh ,
.Ic \eL ,
.Ic \el ,
.Ic \eS ,
.Ic \ev ,
and
.Ic \ex
followed by an argument delimited by a character that cannot occur
in numerical expressions.
However, if any character that can occur in numerical expressions
is found instead of a delimiter, the sequence is considered to end
with that character, and
.Dv ESCAPE_ERROR
is returned.
.El
.It Dv ESCAPE_ERROR
Escape sequences taking an argument but not matching any of the above patterns.
In particular, that happens if the end of the logical input line
is reached before the end of the argument.
.El
.Pp
For sequences that do not take an argument, the function
.Fn mandoc_escape
returns one of the following values:
.Bl -tag -width 2n
.It Dv ESCAPE_SKIPCHAR
The escape sequence
.Qq \ez .
.It Dv ESCAPE_NOSPACE
The escape sequence
.Qq \ec .
.It Dv ESCAPE_IGNORE
The escape sequences
.Qq \ed
and
.Qq \eu .
.El
.Sh FILES
This function is implemented in
.Pa mandoc.c .
.Sh SEE ALSO
.Xr mchars_alloc 3 ,
.Xr mandoc_char 7 ,
.Xr roff 7
.Sh HISTORY
This function has been available since mandoc 1.11.2.
.Sh AUTHORS
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
.An Ingo Schwarze Aq Mt schwarze@openbsd.org
.Sh BUGS
The function doesn't cleanly distinguish between sequences that are
valid and supported, valid and ignored, valid and unsupported,
syntactically invalid, or undefined.
For sequences that are ignored or unsupported, it doesn't tell
whether that deficiency is likely to cause major formatting problems
and/or loss of document content.
The function is already rather complicated and still parses some
sequences incorrectly.
.
.ig
For these sequences, the list given below specifies a starting string
and either the length of the argument or an ending character.
The argument starts after the starting string.
In the former case, the sequence ends with the end of the argument.
In the latter case, the argument ends before the ending character,
and the sequence ends with the ending character.
..
mandoc-1.14.3/mandoc_headers.3 0100644 0002007 0000011 00000022630 13141336266 0015501 0 ustar 00schwarze wsrc .Dd $Mdocdate: July 8 2017 $
.Dt MANDOC_HEADERS 3
.Os
.Sh NAME
.Nm mandoc_headers
.Nd ordering of mandoc include files
.Sh DESCRIPTION
To support a cleaner coding style, the mandoc header files do not
contain any include directives and do not guard against multiple
inclusion.
The application developer has to make sure that the headers are
included in a proper order, and that no header is included more
than once.
.Pp
The headers and functions form three major groups:
.Sx Parser interface ,
.Sx Parser internals ,
and
.Sx Formatter interface .
.Pp
Various rules are given below prohibiting the inclusion of certain
combinations of headers into the same file.
The intention is to keep the following functional components
separate from each other:
.Pp
.Bl -dash -offset indent -compact
.It
.Xr mdoc 7
parser
.It
.Xr man 7
parser
.It
.Xr roff 7
parser
.It
.Xr tbl 7
parser
.It
.Xr eqn 7
parser
.It
terminal formatters
.It
HTML formatters
.It
search tools
.El
.Pp
Note that mere usage of an opaque struct type does
.Em not
require inclusion of the header where that type is defined.
.Ss Parser interface
Each of the following headers can be included without including
any other mandoc header.
These headers should be included before any other mandoc headers.
.Bl -tag -width Ds
.It Qq Pa mandoc_aux.h
Requires
.In sys/types.h
for
.Vt size_t .
.Pp
Provides the utility functions documented in
.Xr mandoc_malloc 3 .
.It Qq Pa mandoc_ohash.h
Requires
.In stddef.h
for
.Vt ptrdiff_t
and
.In stdint.h
for
.Vt uint32_t .
.Pp
Includes
.In ohash.h
and provides
.Fn mandoc_ohash_init .
.It Qq Pa mandoc.h
Requires
.In sys/types.h
for
.Vt size_t .
.Pp
Provides
.Vt enum mandoc_esc ,
.Vt enum mandocerr ,
.Vt enum mandoclevel ,
.Vt enum mandoc_os ,
.Vt enum tbl_cellt ,
.Vt enum tbl_datt ,
.Vt enum tbl_spant ,
.Vt enum eqn_boxt ,
.Vt enum eqn_fontt ,
.Vt enum eqn_pilet ,
.Vt enum eqn_post ,
.Vt struct tbl_opts ,
.Vt struct tbl_cell ,
.Vt struct tbl_row ,
.Vt struct tbl_dat ,
.Vt struct tbl_span ,
.Vt struct eqn_box ,
the function prototype typedef
.Fn mandocmsg ,
the function
.Xr mandoc_escape 3 ,
the functions described in
.Xr mchars_alloc 3 ,
and the functions
.Fn mparse_*
described in
.Xr mandoc 3 .
.Pp
Uses the opaque type
.Vt struct mparse
from
.Pa read.c
for function prototypes.
Uses the type
.Vt struct roff_man
from
.Pa roff.h
as an opaque type for function prototypes.
.It Qq Pa mandoc_xr.h
Provides
.Vt struct mandoc_xr
and the functions
.Fn mandoc_xr_reset ,
.Fn mandoc_xr_add ,
.Fn mandoc_xr_get ,
and
.Fn mandoc_xr_free .
.It Qq Pa roff.h
Requires
.Qq Pa mandoc_ohash.h
for
.Vt struct ohash
and
.Qq Pa mandoc.h
for
.Vt enum mandoc_os .
.Pp
Provides
.Vt enum mdoc_endbody ,
.Vt enum roff_macroset ,
.Vt enum roff_next ,
.Vt enum roff_sec ,
.Vt enum roff_tok ,
.Vt enum roff_type ,
.Vt struct roff_man ,
.Vt struct roff_meta ,
.Vt struct roff_node ,
the constant array
.Va roff_name
and the functions
.Fn deroff ,
.Fn roffhash_alloc ,
.Fn roffhash_find ,
.Fn roffhash_free ,
and
.Fn roff_validate .
.Pp
Uses pointers to the types
.Vt struct mdoc_arg
and
.Vt union mdoc_data
from
.Pa mdoc.h
as opaque struct members.
.El
.Pp
The following two require
.Qq Pa roff.h
but no other mandoc headers.
Afterwards, any other mandoc headers can be included as needed.
.Bl -tag -width Ds
.It Qq Pa mdoc.h
Requires
.In sys/types.h
for
.Vt size_t .
.Pp
Provides
.Vt enum mdocargt ,
.Vt enum mdoc_auth ,
.Vt enum mdoc_disp ,
.Vt enum mdoc_font ,
.Vt enum mdoc_list ,
.Vt struct mdoc_argv ,
.Vt struct mdoc_arg ,
.Vt struct mdoc_an ,
.Vt struct mdoc_bd ,
.Vt struct mdoc_bf ,
.Vt struct mdoc_bl ,
.Vt struct mdoc_rs ,
.Vt union mdoc_data ,
and the functions
.Fn mdoc_*
described in
.Xr mandoc 3 .
.Pp
Uses the type
.Vt struct roff_man
from
.Pa roff.h
as an opaque type for function prototypes.
.Pp
When this header is included, the same file should not include
.Pa libman.h
or
.Pa libroff.h .
.It Qq Pa man.h
Provides the functions
.Fn man_*
described in
.Xr mandoc 3 .
.Pp
Uses the opaque type
.Vt struct mparse
from
.Pa read.c
for function prototypes.
Uses the type
.Vt struct roff_man
from
.Pa roff.h
as an opaque type for function prototypes.
.Pp
When this header is included, the same file should not include
.Pa libmdoc.h
or
.Pa libroff.h .
.El
.Ss Parser internals
The following headers require inclusion of a parser interface header
before they can be included.
All parser interface headers should precede all parser internal headers.
When any parser internal headers are included, the same file should
not include any formatter headers.
.Bl -tag -width Ds
.It Qq Pa libmandoc.h
Requires
.In sys/types.h
for
.Vt size_t
and
.Qq Pa mandoc.h
for
.Vt enum mandocerr .
.Pp
Provides
.Vt enum rofferr ,
.Vt struct buf ,
utility functions needed by multiple parsers,
and the top-level functions to call the parsers.
.Pp
Uses the opaque types
.Vt struct mparse
from
.Pa read.c
and
.Vt struct roff
from
.Pa roff.c
for function prototypes.
Uses the type
.Vt struct roff_man
from
.Pa roff.h
as an opaque type for function prototypes.
.It Qq Pa roff_int.h
Requires
.Qq Pa roff.h
for
.Vt enum roff_type .
.Pp
Provides functions named
.Fn roff_*
to handle roff nodes and the two special functions
.Fn man_breakscope
and
.Fn mdoc_argv_free
because the latter two are needed by
.Qq Pa roff.c .
.Pp
Uses the types
.Vt struct roff_man
and
.Vt struct roff_node
from
.Pa roff.h
and
.Vt struct mdoc_arg
from
.Pa mdoc.h
as opaque types for function prototypes.
.It Qq Pa libmdoc.h
Requires
.Qq Pa roff.h
for
.Vt enum roff_tok
and
.Qq Pa mdoc.h
for
.Vt enum mdoc_*
and
.Vt struct mdoc_* .
.Pp
Provides
.Vt enum margserr ,
.Vt enum mdelim ,
.Vt struct mdoc_macro ,
and many functions internal to the
.Xr mdoc 7
parser.
.Pp
Uses the opaque type
.Vt struct mparse
from
.Pa read.c .
Uses the types
.Vt struct roff_man
and
.Vt struct roff_node
from
.Pa roff.h
as opaque types for function prototypes.
.Pp
When this header is included, the same file should not include
.Pa man.h ,
.Pa libman.h ,
or
.Pa libroff.h .
.It Qq Pa libman.h
Requires
.Qq Pa roff.h
for
.Vt enum roff_tok .
.Pp
Provides
.Vt struct man_macro
and some functions internal to the
.Xr man 7
parser.
.Pp
Uses the types
.Vt struct roff_man
and
.Vt struct roff_node
from
.Pa roff.h
as opaque types for function prototypes.
.Pp
When this header is included, the same file should not include
.Pa mdoc.h ,
.Pa libmdoc.h ,
or
.Pa libroff.h .
.It Qq Pa libroff.h
Requires
.In sys/types.h
for
.Vt size_t
and
.Qq Pa mandoc.h
for
.Vt struct tbl_*
and
.Vt struct eqn_box .
.Pp
Provides
.Vt enum tbl_part ,
.Vt struct tbl_node ,
.Vt struct eqn_def ,
.Vt struct eqn_node ,
and many functions internal to the
.Xr tbl 7
and
.Xr eqn 7
parsers.
.Pp
Uses the opaque type
.Vt struct mparse
from
.Pa read.c .
.Pp
When this header is included, the same file should not include
.Pa man.h ,
.Pa mdoc.h ,
.Pa libman.h ,
or
.Pa libmdoc.h .
.El
.Ss Formatter interface
These headers should be included after any parser interface headers.
No parser internal headers should be included by the same file.
.Bl -tag -width Ds
.It Qq Pa out.h
Requires
.In sys/types.h
for
.Vt size_t .
.Pp
Provides
.Vt enum roffscale ,
.Vt struct roffcol ,
.Vt struct roffsu ,
.Vt struct rofftbl ,
.Fn a2roffsu ,
and
.Fn tblcalc .
.Pp
Uses
.Vt struct tbl_span
from
.Pa mandoc.h
as an opaque type for function prototypes.
.Pp
When this header is included, the same file should not include
.Pa mansearch.h .
.It Qq Pa term.h
Requires
.In sys/types.h
for
.Vt size_t
and
.Qq Pa out.h
for
.Vt struct roffsu
and
.Vt struct rofftbl .
.Pp
Provides
.Vt enum termenc ,
.Vt enum termfont ,
.Vt enum termtype ,
.Vt struct termp_tbl ,
.Vt struct termp ,
.Fn roff_term_pre ,
and many terminal formatting functions.
.Pp
Uses the opaque type
.Vt struct termp_ps
from
.Pa term_ps.c .
Uses
.Vt struct tbl_span
and
.Vt struct eqn_box
from
.Pa mandoc.h
and
.Vt struct roff_meta
and
.Vt struct roff_node
from
.Pa roff.h
as opaque types for function prototypes.
.Pp
When this header is included, the same file should not include
.Pa html.h
or
.Pa mansearch.h .
.It Qq Pa html.h
Requires
.In sys/types.h
for
.Vt size_t
and
.Qq Pa out.h
for
.Vt struct roffsu
and
.Vt struct rofftbl .
.Pp
Provides
.Vt enum htmltag ,
.Vt enum htmlattr ,
.Vt enum htmlfont ,
.Vt struct tag ,
.Vt struct tagq ,
.Vt struct htmlpair ,
.Vt struct html ,
.Fn roff_html_pre ,
and many HTML formatting functions.
.Pp
Uses
.Vt struct tbl_span
and
.Vt struct eqn_box
from
.Pa mandoc.h
and
.Vt struct roff_node
from
.Pa roff.h
as opaque types for function prototypes.
.Pp
When this header is included, the same file should not include
.Pa term.h
or
.Pa mansearch.h .
.It Qq Pa tag.h
Requires
.In sys/types.h
for
.Vt size_t .
.Pp
Provides an interface to generate
.Xr ctags 1
files for the
.Ic :t
functionality mentioned in
.Xr man 1 .
.It Qq Pa main.h
Provides the top level steering functions for all formatters.
.Pp
Uses the type
.Vt struct roff_man
from
.Pa roff.h
as an opaque type for function prototypes.
.It Qq Pa manconf.h
Requires
.In sys/types.h
for
.Vt size_t .
.Pp
Provides
.Vt struct manconf ,
.Vt struct manpaths ,
.Vt struct manoutput ,
and the functions
.Fn manconf_parse ,
.Fn manconf_output ,
.Fn manconf_free ,
and
.Fn manpath_base .
.It Qq Pa mansearch.h
Requires
.In sys/types.h
for
.Vt size_t
and
.In stdint.h
for
.Vt uint64_t .
.Pp
Provides
.Vt enum argmode ,
.Vt struct manpage ,
.Vt struct mansearch ,
and the functions
.Fn mansearch
and
.Fn mansearch_free .
.Pp
Uses
.Vt struct manpaths
from
.Pa manconf.h
as an opaque type for function prototypes.
.Pp
When this header is included, the same file should not include
.Pa out.h ,
.Pa term.h ,
or
.Pa html.h .
.El
mandoc-1.14.3/mandoc_html.3 0100644 0002007 0000011 00000021066 13141336266 0015034 0 ustar 00schwarze wsrc .\" $Id: mandoc_html.3,v 1.10 2017/07/15 17:57:51 schwarze Exp $
.\"
.\" Copyright (c) 2014, 2017 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: July 15 2017 $
.Dt MANDOC_HTML 3
.Os
.Sh NAME
.Nm mandoc_html
.Nd internals of the mandoc HTML formatter
.Sh SYNOPSIS
.In "html.h"
.Ft void
.Fn print_gen_decls "struct html *h"
.Ft void
.Fn print_gen_head "struct html *h"
.Ft struct tag *
.Fo print_otag
.Fa "struct html *h"
.Fa "enum htmltag tag"
.Fa "const char *fmt"
.Fa ...
.Fc
.Ft void
.Fo print_tagq
.Fa "struct html *h"
.Fa "const struct tag *until"
.Fc
.Ft void
.Fo print_stagq
.Fa "struct html *h"
.Fa "const struct tag *suntil"
.Fc
.Ft void
.Fo print_text
.Fa "struct html *h"
.Fa "const char *word"
.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
The mandoc HTML formatter is not a formal library.
However, as it is compiled into more than one program, in particular
.Xr mandoc 1
and
.Xr man.cgi 8 ,
and because it may be security-critical in some contexts,
some documentation is useful to help to use it correctly and
to prevent XSS vulnerabilities.
.Pp
The formatter produces HTML output on the standard output.
Since proper escaping is usually required and best taken care of
at one central place, the language-specific formatters
.Po
.Pa *_html.c ,
see
.Sx FILES
.Pc
are not supposed to print directly to
.Dv stdout
using functions like
.Xr printf 3 ,
.Xr putc 3 ,
.Xr puts 3 ,
or
.Xr write 2 .
Instead, they are expected to use the output functions declared in
.Pa html.h
and implemented as part of the main HTML formatting engine in
.Pa html.c .
.Ss Data structures
These structures are declared in
.Pa html.h .
.Bl -tag -width Ds
.It Vt struct html
Internal state of the HTML formatter.
.It Vt struct tag
One entry for the LIFO stack of HTML elements.
Members are
.Fa "enum htmltag tag"
and
.Fa "struct tag *next" .
.El
.Ss Private interface functions
The function
.Fn print_gen_decls
prints the opening
.Ao Pf \&? Ic xml ? Ac
and
.Aq Pf \&! Ic DOCTYPE
declarations required for the current document type.
.Pp
The function
.Fn print_gen_head
prints the opening
.Aq Ic META
and
.Aq Ic LINK
elements for the document
.Aq Ic HEAD ,
using the
.Fa style
member of
.Fa h
unless that is
.Dv NULL .
It uses
.Fn print_otag
which takes care of properly encoding attributes,
which is relevant for the
.Fa style
link in particular.
.Pp
The function
.Fn print_otag
prints the start tag of an HTML element with the name
.Fa tag ,
optionally including the attributes specified by
.Fa fmt .
If
.Fa fmt
is the empty string, no attributes are written.
Each letter of
.Fa fmt
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 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.
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
to take care of HTML encoding.
If required by the element type, it remembers in
.Fa h
that the element is open.
The function
.Fn print_tagq
is used to close out all open elements up to and including
.Fa until ;
.Fn print_stagq
is a variant to close out all open elements up to but excluding
.Fa suntil .
.Pp
The function
.Fn print_text
prints HTML element content.
It uses the private function
.Fn print_encode
to take care of HTML encoding.
If the document has requested a non-standard font, for example using a
.Xr roff 7
.Ic \ef
font escape sequence,
.Fn print_text
wraps
.Fa word
in an HTML font selection element using the
.Fn print_otag
and
.Fn print_tagq
functions.
.Pp
The function
.Fn html_make_id
takes a node containing one or more text children
and returns a newly allocated string containing the concatenation
of the child strings, with blanks replaced by underscores.
If the node
.Fa n
contains any non-text child node,
.Fn html_make_id
returns
.Dv NULL
instead.
The caller is responsible for freeing the returned string.
.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
.Fn print_eqn ,
.Fn print_tbl ,
and
.Fn print_tblclose
are not yet documented.
.Sh FILES
.Bl -tag -width mandoc_aux.c -compact
.It Pa main.h
declarations of public functions for use by the main program,
not yet documented
.It Pa html.h
declarations of data types and private functions
for use by language-specific HTML formatters
.It Pa html.c
main HTML formatting engine and utility functions
.It Pa mdoc_html.c
.Xr mdoc 7
HTML formatter
.It Pa man_html.c
.Xr man 7
HTML formatter
.It Pa tbl_html.c
.Xr tbl 7
HTML formatter
.It Pa eqn_html.c
.Xr eqn 7
HTML formatter
.It Pa out.h
declarations of data types and private functions
for shared use by all mandoc formatters,
not yet documented
.It Pa out.c
private functions for shared use by all mandoc formatters
.It Pa mandoc_aux.h
declarations of common mandoc utility functions, see
.Xr mandoc 3
.It Pa mandoc_aux.c
implementation of common mandoc utility functions
.El
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr mandoc 3 ,
.Xr man.cgi 8
.Sh AUTHORS
.An -nosplit
The mandoc HTML formatter was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
It is maintained by
.An Ingo Schwarze Aq Mt schwarze@openbsd.org ,
who also wrote this manual.
mandoc-1.14.3/mdoc.7 0100644 0002007 0000011 00000221474 13141336266 0013502 0 ustar 00schwarze wsrc .\" $Id: mdoc.7,v 1.269 2017/07/20 16:24:53 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010, 2011, 2013-2017 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: July 20 2017 $
.Dt MDOC 7
.Os
.Sh NAME
.Nm mdoc
.Nd semantic markup language for formatting manual pages
.Sh DESCRIPTION
The
.Nm mdoc
language supports authoring of manual pages for the
.Xr man 1
utility by allowing semantic annotations of words, phrases,
page sections and complete manual pages.
Such annotations are used by formatting tools to achieve a uniform
presentation across all manuals written in
.Nm ,
and to support hyperlinking if supported by the output medium.
.Pp
This reference document describes the structure of manual pages
and the syntax and usage of the
.Nm
language.
The reference implementation of a parsing and formatting tool is
.Xr mandoc 1 ;
the
.Sx COMPATIBILITY
section describes compatibility with other implementations.
.Pp
In an
.Nm
document, lines beginning with the control character
.Sq \&.
are called
.Dq macro lines .
The first word is the macro name.
It consists of two or three letters.
Most macro names begin with a capital letter.
For a list of available macros, see
.Sx MACRO OVERVIEW .
The words following the macro name are arguments to the macro, optionally
including the names of other, callable macros; see
.Sx MACRO SYNTAX
for details.
.Pp
Lines not beginning with the control character are called
.Dq text lines .
They provide free-form text to be printed; the formatting of the text
depends on the respective processing context:
.Bd -literal -offset indent
\&.Sh Macro lines change control state.
Text lines are interpreted within the current state.
.Ed
.Pp
Many aspects of the basic syntax of the
.Nm
language are based on the
.Xr roff 7
language; see the
.Em LANGUAGE SYNTAX
and
.Em MACRO SYNTAX
sections in the
.Xr roff 7
manual for details, in particular regarding
comments, escape sequences, whitespace, and quoting.
However, using
.Xr roff 7
requests in
.Nm
documents is discouraged;
.Xr mandoc 1
supports some of them merely for backward compatibility.
.Sh MANUAL STRUCTURE
A well-formed
.Nm
document consists of a document prologue followed by one or more
sections.
.Pp
The prologue, which consists of the
.Sx \&Dd ,
.Sx \&Dt ,
and
.Sx \&Os
macros in that order, is required for every document.
.Pp
The first section (sections are denoted by
.Sx \&Sh )
must be the NAME section, consisting of at least one
.Sx \&Nm
followed by
.Sx \&Nd .
.Pp
Following that, convention dictates specifying at least the
.Em SYNOPSIS
and
.Em DESCRIPTION
sections, although this varies between manual sections.
.Pp
The following is a well-formed skeleton
.Nm
file for a utility
.Qq progname :
.Bd -literal -offset indent
\&.Dd $\&Mdocdate$
\&.Dt PROGNAME section
\&.Os
\&.Sh NAME
\&.Nm progname
\&.Nd one line about what it does
\&.\e\(dq .Sh LIBRARY
\&.\e\(dq For sections 2, 3, and 9 only.
\&.\e\(dq Not used in OpenBSD.
\&.Sh SYNOPSIS
\&.Nm progname
\&.Op Fl options
\&.Ar
\&.Sh DESCRIPTION
The
\&.Nm
utility processes files ...
\&.\e\(dq .Sh CONTEXT
\&.\e\(dq For section 9 functions only.
\&.\e\(dq .Sh IMPLEMENTATION NOTES
\&.\e\(dq Not used in OpenBSD.
\&.\e\(dq .Sh RETURN VALUES
\&.\e\(dq For sections 2, 3, and 9 function return values only.
\&.\e\(dq .Sh ENVIRONMENT
\&.\e\(dq For sections 1, 6, 7, and 8 only.
\&.\e\(dq .Sh FILES
\&.\e\(dq .Sh EXIT STATUS
\&.\e\(dq For sections 1, 6, and 8 only.
\&.\e\(dq .Sh EXAMPLES
\&.\e\(dq .Sh DIAGNOSTICS
\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
\&.\e\(dq .Sh ERRORS
\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only.
\&.\e\(dq .Sh SEE ALSO
\&.\e\(dq .Xr foobar 1
\&.\e\(dq .Sh STANDARDS
\&.\e\(dq .Sh HISTORY
\&.\e\(dq .Sh AUTHORS
\&.\e\(dq .Sh CAVEATS
\&.\e\(dq .Sh BUGS
\&.\e\(dq .Sh SECURITY CONSIDERATIONS
\&.\e\(dq Not used in OpenBSD.
.Ed
.Pp
The sections in an
.Nm
document are conventionally ordered as they appear above.
Sections should be composed as follows:
.Bl -ohang -offset Ds
.It Em NAME
The name(s) and a one line description of the documented material.
The syntax for this as follows:
.Bd -literal -offset indent
\&.Nm name0 ,
\&.Nm name1 ,
\&.Nm name2
\&.Nd a one line description
.Ed
.Pp
Multiple
.Sq \&Nm
names should be separated by commas.
.Pp
The
.Sx \&Nm
macro(s) must precede the
.Sx \&Nd
macro.
.Pp
See
.Sx \&Nm
and
.Sx \&Nd .
.It Em LIBRARY
The name of the library containing the documented material, which is
assumed to be a function in a section 2, 3, or 9 manual.
The syntax for this is as follows:
.Bd -literal -offset indent
\&.Lb libarm
.Ed
.Pp
See
.Sx \&Lb .
.It Em SYNOPSIS
Documents the utility invocation syntax, function call syntax, or device
configuration.
.Pp
For the first, utilities (sections 1, 6, and 8), this is
generally structured as follows:
.Bd -literal -offset indent
\&.Nm bar
\&.Op Fl v
\&.Op Fl o Ar file
\&.Op Ar
\&.Nm foo
\&.Op Fl v
\&.Op Fl o Ar file
\&.Op Ar
.Ed
.Pp
Commands should be ordered alphabetically.
.Pp
For the second, function calls (sections 2, 3, 9):
.Bd -literal -offset indent
\&.In header.h
\&.Vt extern const char *global;
\&.Ft "char *"
\&.Fn foo "const char *src"
\&.Ft "char *"
\&.Fn bar "const char *src"
.Ed
.Pp
Ordering of
.Sx \&In ,
.Sx \&Vt ,
.Sx \&Fn ,
and
.Sx \&Fo
macros should follow C header-file conventions.
.Pp
And for the third, configurations (section 4):
.Bd -literal -offset indent
\&.Cd \(dqit* at isa? port 0x2e\(dq
\&.Cd \(dqit* at isa? port 0x4e\(dq
.Ed
.Pp
Manuals not in these sections generally don't need a
.Em SYNOPSIS .
.Pp
Some macros are displayed differently in the
.Em SYNOPSIS
section, particularly
.Sx \&Nm ,
.Sx \&Cd ,
.Sx \&Fd ,
.Sx \&Fn ,
.Sx \&Fo ,
.Sx \&In ,
.Sx \&Vt ,
and
.Sx \&Ft .
All of these macros are output on their own line.
If two such dissimilar macros are pairwise invoked (except for
.Sx \&Ft
before
.Sx \&Fo
or
.Sx \&Fn ) ,
they are separated by a vertical space, unless in the case of
.Sx \&Fo ,
.Sx \&Fn ,
and
.Sx \&Ft ,
which are always separated by vertical space.
.Pp
When text and macros following an
.Sx \&Nm
macro starting an input line span multiple output lines,
all output lines but the first will be indented to align
with the text immediately following the
.Sx \&Nm
macro, up to the next
.Sx \&Nm ,
.Sx \&Sh ,
or
.Sx \&Ss
macro or the end of an enclosing block, whichever comes first.
.It Em DESCRIPTION
This begins with an expansion of the brief, one line description in
.Em NAME :
.Bd -literal -offset indent
The
\&.Nm
utility does this, that, and the other.
.Ed
.Pp
It usually follows with a breakdown of the options (if documenting a
command), such as:
.Bd -literal -offset indent
The arguments are as follows:
\&.Bl \-tag \-width Ds
\&.It Fl v
Print verbose information.
\&.El
.Ed
.Pp
List the options in alphabetical order,
uppercase before lowercase for each letter and
with no regard to whether an option takes an argument.
Put digits in ascending order before all letter options.
.Pp
Manuals not documenting a command won't include the above fragment.
.Pp
Since the
.Em DESCRIPTION
section usually contains most of the text of a manual, longer manuals
often use the
.Sx \&Ss
macro to form subsections.
In very long manuals, the
.Em DESCRIPTION
may be split into multiple sections, each started by an
.Sx \&Sh
macro followed by a non-standard section name, and each having
several subsections, like in the present
.Nm
manual.
.It Em CONTEXT
This section lists the contexts in which functions can be called in section 9.
The contexts are autoconf, process, or interrupt.
.It Em IMPLEMENTATION NOTES
Implementation-specific notes should be kept here.
This is useful when implementing standard functions that may have side
effects or notable algorithmic implications.
.It Em RETURN VALUES
This section documents the
return values of functions in sections 2, 3, and 9.
.Pp
See
.Sx \&Rv .
.It Em ENVIRONMENT
Lists the environment variables used by the utility,
and explains the syntax and semantics of their values.
The
.Xr environ 7
manual provides examples of typical content and formatting.
.Pp
See
.Sx \&Ev .
.It Em FILES
Documents files used.
It's helpful to document both the file name and a short description of how
the file is used (created, modified, etc.).
.Pp
See
.Sx \&Pa .
.It Em EXIT STATUS
This section documents the
command exit status for section 1, 6, and 8 utilities.
Historically, this information was described in
.Em DIAGNOSTICS ,
a practise that is now discouraged.
.Pp
See
.Sx \&Ex .
.It Em EXAMPLES
Example usages.
This often contains snippets of well-formed, well-tested invocations.
Make sure that examples work properly!
.It Em DIAGNOSTICS
Documents error messages.
In section 4 and 9 manuals, these are usually messages printed by the
kernel to the console and to the kernel log.
In section 1, 6, 7, and 8, these are usually messages printed by
userland programs to the standard error output.
.Pp
Historically, this section was used in place of
.Em EXIT STATUS
for manuals in sections 1, 6, and 8; however, this practise is
discouraged.
.Pp
See
.Sx \&Bl
.Fl diag .
.It Em ERRORS
Documents
.Xr errno 2
settings in sections 2, 3, 4, and 9.
.Pp
See
.Sx \&Er .
.It Em SEE ALSO
References other manuals with related topics.
This section should exist for most manuals.
Cross-references should conventionally be ordered first by section, then
alphabetically (ignoring case).
.Pp
References to other documentation concerning the topic of the manual page,
for example authoritative books or journal articles, may also be
provided in this section.
.Pp
See
.Sx \&Rs
and
.Sx \&Xr .
.It Em STANDARDS
References any standards implemented or used.
If not adhering to any standards, the
.Em HISTORY
section should be used instead.
.Pp
See
.Sx \&St .
.It Em HISTORY
A brief history of the subject, including where it was first implemented,
and when it was ported to or reimplemented for the operating system at hand.
.It Em AUTHORS
Credits to the person or persons who wrote the code and/or documentation.
Authors should generally be noted by both name and email address.
.Pp
See
.Sx \&An .
.It Em CAVEATS
Common misuses and misunderstandings should be explained
in this section.
.It Em BUGS
Known bugs, limitations, and work-arounds should be described
in this section.
.It Em SECURITY CONSIDERATIONS
Documents any security precautions that operators should consider.
.El
.Sh MACRO OVERVIEW
This overview is sorted such that macros of similar purpose are listed
together, to help find the best macro for any given purpose.
Deprecated macros are not included in the overview, but can be found below
in the alphabetical
.Sx MACRO REFERENCE .
.Ss Document preamble and NAME section macros
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year
.It Sx \&Dt Ta document title: Ar TITLE section Op Ar arch
.It Sx \&Os Ta operating system version: Op Ar system Op Ar version
.It Sx \&Nm Ta document name (one argument)
.It Sx \&Nd Ta document description (one line)
.El
.Ss Sections and cross references
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Sh Ta section header (one line)
.It Sx \&Ss Ta subsection header (one line)
.It Sx \&Sx Ta internal cross reference to a section or subsection
.It Sx \&Xr Ta cross reference to another manual page: Ar name section
.It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments)
.El
.Ss Displays and lists
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Bd , \&Ed Ta display block:
.Fl Ar type
.Op Fl offset Ar width
.Op Fl compact
.It Sx \&D1 Ta indented display (one line)
.It Sx \&Dl Ta indented literal display (one line)
.It Sx \&Ql Ta in-line literal display: Ql text
.It Sx \&Bl , \&El Ta list block:
.Fl Ar type
.Op Fl width Ar val
.Op Fl offset Ar val
.Op Fl compact
.It Sx \&It Ta list item (syntax depends on Fl Ar type )
.It Sx \&Ta Ta table cell separator in Sx \&Bl Fl column No lists
.It Sx \&Rs , \&%* , \&Re Ta bibliographic block (references)
.El
.Ss Spacing control
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Pf Ta prefix, no following horizontal space (one argument)
.It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments)
.It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)
.It Sx \&Sm Ta switch horizontal spacing mode: Op Cm on | off
.It Sx \&Bk , \&Ek Ta keep block: Fl words
.El
.Ss Semantic markup for command line utilities
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility
.It Sx \&Fl Ta command line options (flags) (>=0 arguments)
.It Sx \&Cm Ta command modifier (>0 arguments)
.It Sx \&Ar Ta command arguments (>=0 arguments)
.It Sx \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure)
.It Sx \&Ic Ta internal or interactive command (>0 arguments)
.It Sx \&Ev Ta environmental variable (>0 arguments)
.It Sx \&Pa Ta file system path (>=0 arguments)
.El
.Ss Semantic markup for function libraries
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Lb Ta function library (one argument)
.It Sx \&In Ta include file (one argument)
.It Sx \&Fd Ta other preprocessor directive (>0 arguments)
.It Sx \&Ft Ta function type (>0 arguments)
.It Sx \&Fo , \&Fc Ta function block: Ar funcname
.It Sx \&Fn Ta function name:
.Op Ar functype
.Ar funcname
.Oo
.Op Ar argtype
.Ar argname
.Oc
.It Sx \&Fa Ta function argument (>0 arguments)
.It Sx \&Vt Ta variable type (>0 arguments)
.It Sx \&Va Ta variable name (>0 arguments)
.It Sx \&Dv Ta defined variable or preprocessor constant (>0 arguments)
.It Sx \&Er Ta error constant (>0 arguments)
.It Sx \&Ev Ta environmental variable (>0 arguments)
.El
.Ss Various semantic markup
.Bl -column "Brq, Bro, Brc" description
.It Sx \&An Ta author name (>0 arguments)
.It Sx \&Lk Ta hyperlink: Ar uri Op Ar name
.It Sx \&Mt Ta Do mailto Dc hyperlink: Ar address
.It Sx \&Cd Ta kernel configuration declaration (>0 arguments)
.It Sx \&Ad Ta memory address (>0 arguments)
.It Sx \&Ms Ta mathematical symbol (>0 arguments)
.El
.Ss Physical markup
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments)
.It Sx \&Sy Ta boldface font (symbolic) (>0 arguments)
.It Sx \&Li Ta typewriter font (literal) (>0 arguments)
.It Sx \&No Ta return to roman font (normal) (no arguments)
.It Sx \&Bf , \&Ef Ta font block:
.Op Fl Ar type | Cm \&Em | \&Li | \&Sy
.El
.Ss Physical enclosures
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text
.It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text
.It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text
.It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text
.It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text
.It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text
.It Sx \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text
.It Sx \&Eo , \&Ec Ta generic enclosure
.El
.Ss Text production
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
.It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
.It Sx \&St Ta reference to a standards document (one argument)
.It Sx \&At Ta At
.It Sx \&Bx Ta Bx
.It Sx \&Bsx Ta Bsx
.It Sx \&Nx Ta Nx
.It Sx \&Fx Ta Fx
.It Sx \&Ox Ta Ox
.It Sx \&Dx Ta Dx
.El
.Sh MACRO REFERENCE
This section is a canonical reference of all macros, arranged
alphabetically.
For the scoping of individual macros, see
.Sx MACRO SYNTAX .
.Ss \&%A
Author name of an
.Sx \&Rs
block.
Multiple authors should each be accorded their own
.Sx \%%A
line.
Author names should be ordered with full or abbreviated forename(s)
first, then full surname.
.Ss \&%B
Book title of an
.Sx \&Rs
block.
This macro may also be used in a non-bibliographic context when
referring to book titles.
.Ss \&%C
Publication city or location of an
.Sx \&Rs
block.
.Ss \&%D
Publication date of an
.Sx \&Rs
block.
Recommended formats of arguments are
.Ar month day , year
or just
.Ar year .
.Ss \&%I
Publisher or issuer name of an
.Sx \&Rs
block.
.Ss \&%J
Journal name of an
.Sx \&Rs
block.
.Ss \&%N
Issue number (usually for journals) of an
.Sx \&Rs
block.
.Ss \&%O
Optional information of an
.Sx \&Rs
block.
.Ss \&%P
Book or journal page number of an
.Sx \&Rs
block.
.Ss \&%Q
Institutional author (school, government, etc.) of an
.Sx \&Rs
block.
Multiple institutional authors should each be accorded their own
.Sx \&%Q
line.
.Ss \&%R
Technical report name of an
.Sx \&Rs
block.
.Ss \&%T
Article title of an
.Sx \&Rs
block.
This macro may also be used in a non-bibliographical context when
referring to article titles.
.Ss \&%U
URI of reference document.
.Ss \&%V
Volume number of an
.Sx \&Rs
block.
.Ss \&Ac
Close an
.Sx \&Ao
block.
Does not have any tail arguments.
.Ss \&Ad
Memory address.
Do not use this for postal addresses.
.Pp
Examples:
.Dl \&.Ad [0,$]
.Dl \&.Ad 0x00000000
.Ss \&An
Author name.
Can be used both for the authors of the program, function, or driver
documented in the manual, or for the authors of the manual itself.
Requires either the name of an author or one of the following arguments:
.Pp
.Bl -tag -width "-nosplitX" -offset indent -compact
.It Fl split
Start a new output line before each subsequent invocation of
.Sx \&An .
.It Fl nosplit
The opposite of
.Fl split .
.El
.Pp
The default is
.Fl nosplit .
The effect of selecting either of the
.Fl split
modes ends at the beginning of the
.Em AUTHORS
section.
In the
.Em AUTHORS
section, the default is
.Fl nosplit
for the first author listing and
.Fl split
for all other author listings.
.Pp
Examples:
.Dl \&.An -nosplit
.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
.Ss \&Ao
Begin a block enclosed by angle brackets.
Does not have any head arguments.
.Pp
Examples:
.Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
.Pp
See also
.Sx \&Aq .
.Ss \&Ap
Inserts an apostrophe without any surrounding whitespace.
This is generally used as a grammatical device when referring to the verb
form of a function.
.Pp
Examples:
.Dl \&.Fn execve \&Ap d
.Ss \&Aq
Encloses its arguments in angle brackets.
.Pp
Examples:
.Dl \&.Fl -key= \&Ns \&Aq \&Ar val
.Pp
.Em Remarks :
this macro is often abused for rendering URIs, which should instead use
.Sx \&Lk
or
.Sx \&Mt ,
or to note pre-processor
.Dq Li #include
statements, which should use
.Sx \&In .
.Pp
See also
.Sx \&Ao .
.Ss \&Ar
Command arguments.
If an argument is not provided, the string
.Dq file ...\&
is used as a default.
.Pp
Examples:
.Dl ".Fl o Ar file"
.Dl ".Ar"
.Dl ".Ar arg1 , arg2 ."
.Pp
The arguments to the
.Sx \&Ar
macro are names and placeholders for command arguments;
for fixed strings to be passed verbatim as arguments, use
.Sx \&Fl
or
.Sx \&Cm .
.Ss \&At
Formats an
.At
version.
Accepts one optional argument:
.Pp
.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
.It Cm v[1-7] | 32v
A version of
.At .
.It Cm III
.At III .
.It Cm V | V.[1-4]
A version of
.At V .
.El
.Pp
Note that these arguments do not begin with a hyphen.
.Pp
Examples:
.Dl \&.At
.Dl \&.At III
.Dl \&.At V.1
.Pp
See also
.Sx \&Bsx ,
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
and
.Sx \&Ox .
.Ss \&Bc
Close a
.Sx \&Bo
block.
Does not have any tail arguments.
.Ss \&Bd
Begin a display block.
Its syntax is as follows:
.Bd -ragged -offset indent
.Pf \. Sx \&Bd
.Fl Ns Ar type
.Op Fl offset Ar width
.Op Fl compact
.Ed
.Pp
Display blocks are used to select a different indentation and
justification than the one used by the surrounding text.
They may contain both macro lines and text lines.
By default, a display block is preceded by a vertical space.
.Pp
The
.Ar type
must be one of the following:
.Bl -tag -width 13n -offset indent
.It Fl centered
Produce one output line from each input line, and center-justify each line.
Using this display type is not recommended; many
.Nm
implementations render it poorly.
.It Fl filled
Change the positions of line breaks to fill each line, and left- and
right-justify the resulting block.
.It Fl literal
Produce one output line from each input line,
and do not justify the block at all.
Preserve white space as it appears in the input.
Always use a constant-width font.
Use this for displaying source code.
.It Fl ragged
Change the positions of line breaks to fill each line, and left-justify
the resulting block.
.It Fl unfilled
The same as
.Fl literal ,
but using the same font as for normal text, which is a variable width font
if supported by the output device.
.El
.Pp
The
.Ar type
must be provided first.
Additional arguments may follow:
.Bl -tag -width 13n -offset indent
.It Fl offset Ar width
Indent the display by the
.Ar width ,
which may be one of the following:
.Bl -item
.It
One of the pre-defined strings
.Cm indent ,
the width of a standard indentation (six constant width characters);
.Cm indent-two ,
twice
.Cm indent ;
.Cm left ,
which has no effect;
.Cm right ,
which justifies to the right margin; or
.Cm center ,
which aligns around an imagined center axis.
.It
A macro invocation, which selects a predefined width
associated with that macro.
The most popular is the imaginary macro
.Ar \&Ds ,
which resolves to
.Sy 6n .
.It
A scaling width as described in
.Xr roff 7 .
.It
An arbitrary string, which indents by the length of this string.
.El
.Pp
When the argument is missing,
.Fl offset
is ignored.
.It Fl compact
Do not assert vertical space before the display.
.El
.Pp
Examples:
.Bd -literal -offset indent
\&.Bd \-literal \-offset indent \-compact
Hello world.
\&.Ed
.Ed
.Pp
See also
.Sx \&D1
and
.Sx \&Dl .
.Ss \&Bf
Change the font mode for a scoped block of text.
Its syntax is as follows:
.Bd -ragged -offset indent
.Pf \. Sx \&Bf
.Oo
.Fl emphasis | literal | symbolic |
.Cm \&Em | \&Li | \&Sy
.Oc
.Ed
.Pp
The
.Fl emphasis
and
.Cm \&Em
argument are equivalent, as are
.Fl symbolic
and
.Cm \&Sy ,
and
.Fl literal
and
.Cm \&Li .
Without an argument, this macro does nothing.
The font mode continues until broken by a new font mode in a nested
scope or
.Sx \&Ef
is encountered.
.Pp
See also
.Sx \&Li ,
.Sx \&Ef ,
.Sx \&Em ,
and
.Sx \&Sy .
.Ss \&Bk
For each macro, keep its output together on the same output line,
until the end of the macro or the end of the input line is reached,
whichever comes first.
Line breaks in text lines are unaffected.
The syntax is as follows:
.Pp
.D1 Pf \. Sx \&Bk Fl words
.Pp
The
.Fl words
argument is required; additional arguments are ignored.
.Pp
The following example will not break within each
.Sx \&Op
macro line:
.Bd -literal -offset indent
\&.Bk \-words
\&.Op Fl f Ar flags
\&.Op Fl o Ar output
\&.Ek
.Ed
.Pp
Be careful in using over-long lines within a keep block!
Doing so will clobber the right margin.
.Ss \&Bl
Begin a list.
Lists consist of items specified using the
.Sx \&It
macro, containing a head or a body or both.
The list syntax is as follows:
.Bd -ragged -offset indent
.Pf \. Sx \&Bl
.Fl Ns Ar type
.Op Fl width Ar val
.Op Fl offset Ar val
.Op Fl compact
.Op HEAD ...
.Ed
.Pp
The list
.Ar type
is mandatory and must be specified first.
The
.Fl width
and
.Fl offset
arguments accept macro names as described for
.Sx \&Bd
.Fl offset ,
scaling widths as described in
.Xr roff 7 ,
or use the length of the given string.
The
.Fl offset
is a global indentation for the whole list, affecting both item heads
and bodies.
For those list types supporting it, the
.Fl width
argument requests an additional indentation of item bodies,
to be added to the
.Fl offset .
Unless the
.Fl compact
argument is specified, list entries are separated by vertical space.
.Pp
A list must specify one of the following list types:
.Bl -tag -width 12n -offset indent
.It Fl bullet
No item heads can be specified, but a bullet will be printed at the head
of each item.
Item bodies start on the same output line as the bullet
and are indented according to the
.Fl width
argument.
.It Fl column
A columnated list.
The
.Fl width
argument has no effect; instead, the string length of each argument
specifies the width of one column.
If the first line of the body of a
.Fl column
list is not an
.Sx \&It
macro line,
.Sx \&It
contexts spanning one input line each are implied until an
.Sx \&It
macro line is encountered, at which point items start being interpreted as
described in the
.Sx \&It
documentation.
.It Fl dash
Like
.Fl bullet ,
except that dashes are used in place of bullets.
.It Fl diag
Like
.Fl inset ,
except that item heads are not parsed for macro invocations.
Most often used in the
.Em DIAGNOSTICS
section with error constants in the item heads.
.It Fl enum
A numbered list.
No item heads can be specified.
Formatted like
.Fl bullet ,
except that cardinal numbers are used in place of bullets,
starting at 1.
.It Fl hang
Like
.Fl tag ,
except that the first lines of item bodies are not indented, but follow
the item heads like in
.Fl inset
lists.
.It Fl hyphen
Synonym for
.Fl dash .
.It Fl inset
Item bodies follow items heads on the same line, using normal inter-word
spacing.
Bodies are not indented, and the
.Fl width
argument is ignored.
.It Fl item
No item heads can be specified, and none are printed.
Bodies are not indented, and the
.Fl width
argument is ignored.
.It Fl ohang
Item bodies start on the line following item heads and are not indented.
The
.Fl width
argument is ignored.
.It Fl tag
Item bodies are indented according to the
.Fl width
argument.
When an item head fits inside the indentation, the item body follows
this head on the same output line.
Otherwise, the body starts on the output line following the head.
.El
.Pp
Lists may be nested within lists and displays.
Nesting of
.Fl column
and
.Fl enum
lists may not be portable.
.Pp
See also
.Sx \&El
and
.Sx \&It .
.Ss \&Bo
Begin a block enclosed by square brackets.
Does not have any head arguments.
.Pp
Examples:
.Bd -literal -offset indent -compact
\&.Bo 1 ,
\&.Dv BUFSIZ \&Bc
.Ed
.Pp
See also
.Sx \&Bq .
.Ss \&Bq
Encloses its arguments in square brackets.
.Pp
Examples:
.Dl \&.Bq 1 , \&Dv BUFSIZ
.Pp
.Em Remarks :
this macro is sometimes abused to emulate optional arguments for
commands; the correct macros to use for this purpose are
.Sx \&Op ,
.Sx \&Oo ,
and
.Sx \&Oc .
.Pp
See also
.Sx \&Bo .
.Ss \&Brc
Close a
.Sx \&Bro
block.
Does not have any tail arguments.
.Ss \&Bro
Begin a block enclosed by curly braces.
Does not have any head arguments.
.Pp
Examples:
.Bd -literal -offset indent -compact
\&.Bro 1 , ... ,
\&.Va n \&Brc
.Ed
.Pp
See also
.Sx \&Brq .
.Ss \&Brq
Encloses its arguments in curly braces.
.Pp
Examples:
.Dl \&.Brq 1 , ... , \&Va n
.Pp
See also
.Sx \&Bro .
.Ss \&Bsx
Format the
.Bsx
version provided as an argument, or a default value if
no argument is provided.
.Pp
Examples:
.Dl \&.Bsx 1.0
.Dl \&.Bsx
.Pp
See also
.Sx \&At ,
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
and
.Sx \&Ox .
.Ss \&Bt
Supported only for compatibility, do not use this in new manuals.
Prints
.Dq is currently in beta test.
.Ss \&Bx
Format the
.Bx
version provided as an argument, or a default value if no
argument is provided.
.Pp
Examples:
.Dl \&.Bx 4.3 Tahoe
.Dl \&.Bx 4.4
.Dl \&.Bx
.Pp
See also
.Sx \&At ,
.Sx \&Bsx ,
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
and
.Sx \&Ox .
.Ss \&Cd
Kernel configuration declaration.
This denotes strings accepted by
.Xr config 8 .
It is most often used in section 4 manual pages.
.Pp
Examples:
.Dl \&.Cd device le0 at scode?
.Pp
.Em Remarks :
this macro is commonly abused by using quoted literals to retain
whitespace and align consecutive
.Sx \&Cd
declarations.
This practise is discouraged.
.Ss \&Cm
Command modifiers.
Typically used for fixed strings passed as arguments, unless
.Sx \&Fl
is more appropriate.
Also useful when specifying configuration options or keys.
.Pp
Examples:
.Dl ".Nm mt Fl f Ar device Cm rewind"
.Dl ".Nm ps Fl o Cm pid , Ns Cm command"
.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2"
.Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa"
.Dl ".Cm LogLevel Dv DEBUG"
.Ss \&D1
One-line indented display.
This is formatted by the default rules and is useful for simple indented
statements.
It is followed by a newline.
.Pp
Examples:
.Dl \&.D1 \&Fl abcdefgh
.Pp
See also
.Sx \&Bd
and
.Sx \&Dl .
.Ss \&Db
This macro is obsolete.
No replacement is needed.
It is ignored by
.Xr mandoc 1
and groff including its arguments.
It was formerly used to toggle a debugging mode.
.Ss \&Dc
Close a
.Sx \&Do
block.
Does not have any tail arguments.
.Ss \&Dd
Document date for display in the page footer.
This is the mandatory first macro of any
.Nm
manual.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Dd Ar month day , year
.Pp
The
.Ar month
is the full English month name, the
.Ar day
is an optionally zero-padded numeral, and the
.Ar year
is the full four-digit year.
.Pp
Other arguments are not portable; the
.Xr mandoc 1
utility handles them as follows:
.Bl -dash -offset 3n -compact
.It
To have the date automatically filled in by the
.Ox
version of
.Xr cvs 1 ,
the special string
.Dq $\&Mdocdate$
can be given as an argument.
.It
The traditional, purely numeric
.Xr man 7
format
.Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day
is accepted, too.
.It
If a date string cannot be parsed, it is used verbatim.
.It
If no date string is given, the current date is used.
.El
.Pp
Examples:
.Dl \&.Dd $\&Mdocdate$
.Dl \&.Dd $\&Mdocdate: July 21 2007$
.Dl \&.Dd July 21, 2007
.Pp
See also
.Sx \&Dt
and
.Sx \&Os .
.Ss \&Dl
One-line indented display.
This is formatted as literal text and is useful for commands and
invocations.
It is followed by a newline.
.Pp
Examples:
.Dl \&.Dl % mandoc mdoc.7 \e(ba less
.Pp
See also
.Sx \&Ql ,
.Sx \&Bd
.Fl literal ,
and
.Sx \&D1 .
.Ss \&Do
Begin a block enclosed by double quotes.
Does not have any head arguments.
.Pp
Examples:
.Bd -literal -offset indent -compact
\&.Do
April is the cruellest month
\&.Dc
\e(em T.S. Eliot
.Ed
.Pp
See also
.Sx \&Dq .
.Ss \&Dq
Encloses its arguments in
.Dq typographic
double-quotes.
.Pp
Examples:
.Bd -literal -offset indent -compact
\&.Dq April is the cruellest month
\e(em T.S. Eliot
.Ed
.Pp
See also
.Sx \&Qq ,
.Sx \&Sq ,
and
.Sx \&Do .
.Ss \&Dt
Document title for display in the page header.
This is the mandatory second macro of any
.Nm
file.
Its syntax is as follows:
.Bd -ragged -offset indent
.Pf \. Sx \&Dt
.Ar TITLE
.Ar section
.Op Ar arch
.Ed
.Pp
Its arguments are as follows:
.Bl -tag -width section -offset 2n
.It Ar TITLE
The document's title (name), defaulting to
.Dq UNTITLED
if unspecified.
To achieve a uniform appearance of page header lines,
it should by convention be all caps.
.It Ar section
The manual section.
This may be one of
.Cm 1
.Pq General Commands ,
.Cm 2
.Pq System Calls ,
.Cm 3
.Pq Library Functions ,
.Cm 3p
.Pq Perl Library ,
.Cm 4
.Pq Device Drivers ,
.Cm 5
.Pq File Formats ,
.Cm 6
.Pq Games ,
.Cm 7
.Pq Miscellaneous Information ,
.Cm 8
.Pq System Manager's Manual ,
or
.Cm 9
.Pq Kernel Developer's Manual .
It should correspond to the manual's filename suffix and defaults to
the empty string if unspecified.
.It Ar arch
This specifies the machine architecture a manual page applies to,
where relevant, for example
.Cm alpha ,
.Cm amd64 ,
.Cm i386 ,
or
.Cm sparc64 .
The list of valid architectures varies by operating system.
.El
.Pp
Examples:
.Dl \&.Dt FOO 1
.Dl \&.Dt FOO 9 i386
.Pp
See also
.Sx \&Dd
and
.Sx \&Os .
.Ss \&Dv
Defined variables such as preprocessor constants, constant symbols,
enumeration values, and so on.
.Pp
Examples:
.Dl \&.Dv NULL
.Dl \&.Dv BUFSIZ
.Dl \&.Dv STDOUT_FILENO
.Pp
See also
.Sx \&Er
and
.Sx \&Ev
for special-purpose constants,
.Sx \&Va
for variable symbols, and
.Sx \&Fd
for listing preprocessor variable definitions in the
.Em SYNOPSIS .
.Ss \&Dx
Format the
.Dx
version provided as an argument, or a default
value if no argument is provided.
.Pp
Examples:
.Dl \&.Dx 2.4.1
.Dl \&.Dx
.Pp
See also
.Sx \&At ,
.Sx \&Bsx ,
.Sx \&Bx ,
.Sx \&Fx ,
.Sx \&Nx ,
and
.Sx \&Ox .
.Ss \&Ec
Close a scope started by
.Sx \&Eo .
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Ec Op Ar TERM
.Pp
The
.Ar TERM
argument is used as the enclosure tail, for example, specifying \e(rq
will emulate
.Sx \&Dc .
.Ss \&Ed
End a display context started by
.Sx \&Bd .
.Ss \&Ef
End a font mode context started by
.Sx \&Bf .
.Ss \&Ek
End a keep context started by
.Sx \&Bk .
.Ss \&El
End a list context started by
.Sx \&Bl .
.Pp
See also
.Sx \&Bl
and
.Sx \&It .
.Ss \&Em
Request an italic font.
If the output device does not provide that, underline.
.Pp
This is most often used for stress emphasis (not to be confused with
importance, see
.Sx \&Sy ) .
In the rare cases where none of the semantic markup macros fit,
it can also be used for technical terms and placeholders, except
that for syntax elements,
.Sx \&Sy
and
.Sx \&Ar
are preferred, respectively.
.Pp
Examples:
.Bd -literal -compact -offset indent
Selected lines are those
\&.Em not
matching any of the specified patterns.
Some of the functions use a
\&.Em hold space
to save the pattern space for subsequent retrieval.
.Ed
.Pp
See also
.Sx \&Bf ,
.Sx \&Li ,
.Sx \&No ,
and
.Sx \&Sy .
.Ss \&En
This macro is obsolete.
Use
.Sx \&Eo
or any of the other enclosure macros.
.Pp
It encloses its argument in the delimiters specified by the last
.Sx \&Es
macro.
.Ss \&Eo
An arbitrary enclosure.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Eo Op Ar TERM
.Pp
The
.Ar TERM
argument is used as the enclosure head, for example, specifying \e(lq
will emulate
.Sx \&Do .
.Ss \&Er
Error constants for definitions of the
.Va errno
libc global variable.
This is most often used in section 2 and 3 manual pages.
.Pp
Examples:
.Dl \&.Er EPERM
.Dl \&.Er ENOENT
.Pp
See also
.Sx \&Dv
for general constants.
.Ss \&Es
This macro is obsolete.
Use
.Sx \&Eo
or any of the other enclosure macros.
.Pp
It takes two arguments, defining the delimiters to be used by subsequent
.Sx \&En
macros.
.Ss \&Ev
Environmental variables such as those specified in
.Xr environ 7 .
.Pp
Examples:
.Dl \&.Ev DISPLAY
.Dl \&.Ev PATH
.Pp
See also
.Sx \&Dv
for general constants.
.Ss \&Ex
Insert a standard sentence regarding command exit values of 0 on success
and >0 on failure.
This is most often used in section 1, 6, and 8 manual pages.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
.Pp
If
.Ar utility
is not specified, the document's name set by
.Sx \&Nm
is used.
Multiple
.Ar utility
arguments are treated as separate utilities.
.Pp
See also
.Sx \&Rv .
.Ss \&Fa
Function argument or parameter.
Its syntax is as follows:
.Bd -ragged -offset indent
.Pf \. Sx \&Fa
.Qo
.Op Ar argtype
.Op Ar argname
.Qc Ar \&...
.Ed
.Pp
Each argument may be a name and a type (recommended for the
.Em SYNOPSIS
section), a name alone (for function invocations),
or a type alone (for function prototypes).
If both a type and a name are given or if the type consists of multiple
words, all words belonging to the same function argument have to be
given in a single argument to the
.Sx \&Fa
macro.
.Pp
This macro is also used to specify the field name of a structure.
.Pp
Most often, the
.Sx \&Fa
macro is used in the
.Em SYNOPSIS
within
.Sx \&Fo
blocks when documenting multi-line function prototypes.
If invoked with multiple arguments, the arguments are separated by a
comma.
Furthermore, if the following macro is another
.Sx \&Fa ,
the last argument will also have a trailing comma.
.Pp
Examples:
.Dl \&.Fa \(dqconst char *p\(dq
.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
.Dl \&.Fa \(dqchar *\(dq size_t
.Pp
See also
.Sx \&Fo .
.Ss \&Fc
End a function context started by
.Sx \&Fo .
.Ss \&Fd
Preprocessor directive, in particular for listing it in the
.Em SYNOPSIS .
Historically, it was also used to document include files.
The latter usage has been deprecated in favour of
.Sx \&In .
.Pp
Its syntax is as follows:
.Bd -ragged -offset indent
.Pf \. Sx \&Fd
.Li # Ns Ar directive
.Op Ar argument ...
.Ed
.Pp
Examples:
.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler
.Dl \&.Fd #define SIO_MAXNFDS
.Dl \&.Fd #ifdef FS_DEBUG
.Dl \&.Ft void
.Dl \&.Fn dbg_open \(dqconst char *\(dq
.Dl \&.Fd #endif
.Pp
See also
.Sx MANUAL STRUCTURE ,
.Sx \&In ,
and
.Sx \&Dv .
.Ss \&Fl
Command-line flag or option.
Used when listing arguments to command-line utilities.
Prints a fixed-width hyphen
.Sq \-
directly followed by each argument.
If no arguments are provided, a hyphen is printed followed by a space.
If the argument is a macro, a hyphen is prefixed to the subsequent macro
output.
.Pp
Examples:
.Dl ".Fl R Op Fl H | L | P"
.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
.Dl ".Fl type Cm d Fl name Pa CVS"
.Dl ".Fl Ar signal_number"
.Dl ".Fl o Fl"
.Pp
See also
.Sx \&Cm .
.Ss \&Fn
A function name.
Its syntax is as follows:
.Bd -ragged -offset indent
.Pf . Sx \&Fn
.Op Ar functype
.Ar funcname
.Op Oo Ar argtype Oc Ar argname
.Ed
.Pp
Function arguments are surrounded in parenthesis and
are delimited by commas.
If no arguments are specified, blank parenthesis are output.
In the
.Em SYNOPSIS
section, this macro starts a new output line,
and a blank line is automatically inserted between function definitions.
.Pp
Examples:
.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
.Dl \&.Fn funcname \(dqint arg0\(dq
.Dl \&.Fn funcname arg0
.Pp
.Bd -literal -offset indent -compact
\&.Ft functype
\&.Fn funcname
.Ed
.Pp
When referring to a function documented in another manual page, use
.Sx \&Xr
instead.
See also
.Sx MANUAL STRUCTURE ,
.Sx \&Fo ,
and
.Sx \&Ft .
.Ss \&Fo
Begin a function block.
This is a multi-line version of
.Sx \&Fn .
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Fo Ar funcname
.Pp
Invocations usually occur in the following context:
.Bd -ragged -offset indent
.Pf \. Sx \&Ft Ar functype
.br
.Pf \. Sx \&Fo Ar funcname
.br
.Pf \. Sx \&Fa Qq Ar argtype Ar argname
.br
\&.\.\.
.br
.Pf \. Sx \&Fc
.Ed
.Pp
A
.Sx \&Fo
scope is closed by
.Sx \&Fc .
.Pp
See also
.Sx MANUAL STRUCTURE ,
.Sx \&Fa ,
.Sx \&Fc ,
and
.Sx \&Ft .
.Ss \&Fr
This macro is obsolete.
No replacement markup is needed.
.Pp
It was used to show numerical function return values in an italic font.
.Ss \&Ft
A function type.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Ft Ar functype
.Pp
In the
.Em SYNOPSIS
section, a new output line is started after this macro.
.Pp
Examples:
.Dl \&.Ft int
.Bd -literal -offset indent -compact
\&.Ft functype
\&.Fn funcname
.Ed
.Pp
See also
.Sx MANUAL STRUCTURE ,
.Sx \&Fn ,
and
.Sx \&Fo .
.Ss \&Fx
Format the
.Fx
version provided as an argument, or a default value
if no argument is provided.
.Pp
Examples:
.Dl \&.Fx 7.1
.Dl \&.Fx
.Pp
See also
.Sx \&At ,
.Sx \&Bsx ,
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Nx ,
and
.Sx \&Ox .
.Ss \&Hf
This macro is not implemented in
.Xr mandoc 1 .
.Pp
It was used to include the contents of a (header) file literally.
The syntax was:
.Pp
.Dl Pf . Sx \&Hf Ar filename
.Ss \&Ic
Designate an internal or interactive command.
This is similar to
.Sx \&Cm
but used for instructions rather than values.
.Pp
Examples:
.Dl \&.Ic :wq
.Dl \&.Ic hash
.Dl \&.Ic alias
.Pp
Note that using
.Sx \&Bd Fl literal
or
.Sx \&D1
is preferred for displaying code; the
.Sx \&Ic
macro is used when referring to specific instructions.
.Ss \&In
The name of an include file.
This macro is most often used in section 2, 3, and 9 manual pages.
.Pp
When invoked as the first macro on an input line in the
.Em SYNOPSIS
section, the argument is displayed in angle brackets
and preceded by
.Qq #include ,
and a blank line is inserted in front if there is a preceding
function declaration.
In other sections, it only encloses its argument in angle brackets
and causes no line break.
.Pp
Examples:
.Dl \&.In sys/types.h
.Pp
See also
.Sx MANUAL STRUCTURE .
.Ss \&It
A list item.
The syntax of this macro depends on the list type.
.Pp
Lists
of type
.Fl hang ,
.Fl ohang ,
.Fl inset ,
and
.Fl diag
have the following syntax:
.Pp
.D1 Pf \. Sx \&It Ar args
.Pp
Lists of type
.Fl bullet ,
.Fl dash ,
.Fl enum ,
.Fl hyphen
and
.Fl item
have the following syntax:
.Pp
.D1 Pf \. Sx \&It
.Pp
with subsequent lines interpreted within the scope of the
.Sx \&It
until either a closing
.Sx \&El
or another
.Sx \&It .
.Pp
The
.Fl tag
list has the following syntax:
.Pp
.D1 Pf \. Sx \&It Op Cm args
.Pp
Subsequent lines are interpreted as with
.Fl bullet
and family.
The line arguments correspond to the list's left-hand side; body
arguments correspond to the list's contents.
.Pp
The
.Fl column
list is the most complicated.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
.D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
.Pp
The arguments consist of one or more lines of text and macros
representing a complete table line.
Cells within the line are delimited by the special
.Sx \&Ta
block macro or by literal tab characters.
.Pp
Using literal tabs is strongly discouraged because they are very
hard to use correctly and
.Nm
code using them is very hard to read.
In particular, a blank character is syntactically significant
before and after the literal tab character.
If a word precedes or follows the tab without an intervening blank,
that word is never interpreted as a macro call, but always output
literally.
.Pp
The tab cell delimiter may only be used within the
.Sx \&It
line itself; on following lines, only the
.Sx \&Ta
macro can be used to delimit cells, and portability requires that
.Sx \&Ta
is called by other macros: some parsers do not recognize it when
it appears as the first macro on a line.
.Pp
Note that quoted strings may span tab-delimited cells on an
.Sx \&It
line.
For example,
.Pp
.Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&;
.Pp
will preserve the whitespace before both commas,
but not the whitespace before the semicolon.
.Pp
See also
.Sx \&Bl .
.Ss \&Lb
Specify a library.
The syntax is as follows:
.Pp
.D1 Pf \. Sx \&Lb Ar library
.Pp
The
.Ar library
parameter may be a system library, such as
.Cm libz
or
.Cm libpam ,
in which case a small library description is printed next to the linker
invocation; or a custom library, in which case the library name is
printed in quotes.
This is most commonly used in the
.Em SYNOPSIS
section as described in
.Sx MANUAL STRUCTURE .
.Pp
Examples:
.Dl \&.Lb libz
.Dl \&.Lb libmandoc
.Ss \&Li
Denotes text that should be in a
.Li literal
font mode.
Note that this is a presentation term and should not be used for
stylistically decorating technical terms.
.Pp
On terminal output devices, this is often indistinguishable from
normal text.
.Pp
See also
.Sx \&Bf ,
.Sx \&Em ,
.Sx \&No ,
and
.Sx \&Sy .
.Ss \&Lk
Format a hyperlink.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Lk Ar uri Op Ar name
.Pp
Examples:
.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
.Dl \&.Lk http://bsd.lv
.Pp
See also
.Sx \&Mt .
.Ss \&Lp
Synonym for
.Sx \&Pp .
.Ss \&Ms
Display a mathematical symbol.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Ms Ar symbol
.Pp
Examples:
.Dl \&.Ms sigma
.Dl \&.Ms aleph
.Ss \&Mt
Format a
.Dq mailto:
hyperlink.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Mt Ar address
.Pp
Examples:
.Dl \&.Mt discuss@manpages.bsd.lv
.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
.Ss \&Nd
A one line description of the manual's content.
This is the mandatory last macro of the
.Em NAME
section and not appropriate for other sections.
.Pp
Examples:
.Dl Pf . Sx \&Nd mdoc language reference
.Dl Pf . Sx \&Nd format and display UNIX manuals
.Pp
The
.Sx \&Nd
macro technically accepts child macros and terminates with a subsequent
.Sx \&Sh
invocation.
Do not assume this behaviour: some
.Xr whatis 1
database generators are not smart enough to parse more than the line
arguments and will display macros verbatim.
.Pp
See also
.Sx \&Nm .
.Ss \&Nm
The name of the manual page, or \(em in particular in section 1, 6,
and 8 pages \(em of an additional command or feature documented in
the manual page.
When first invoked, the
.Sx \&Nm
macro expects a single argument, the name of the manual page.
Usually, the first invocation happens in the
.Em NAME
section of the page.
The specified name will be remembered and used whenever the macro is
called again without arguments later in the page.
The
.Sx \&Nm
macro uses
.Sx Block full-implicit
semantics when invoked as the first macro on an input line in the
.Em SYNOPSIS
section; otherwise, it uses ordinary
.Sx In-line
semantics.
.Pp
Examples:
.Bd -literal -offset indent
\&.Sh SYNOPSIS
\&.Nm cat
\&.Op Fl benstuv
\&.Op Ar
.Ed
.Pp
In the
.Em SYNOPSIS
of section 2, 3 and 9 manual pages, use the
.Sx \&Fn
macro rather than
.Sx \&Nm
to mark up the name of the manual page.
.Ss \&No
Normal text.
Closes the scope of any preceding in-line macro.
When used after physical formatting macros like
.Sx \&Em
or
.Sx \&Sy ,
switches back to the standard font face and weight.
Can also be used to embed plain text strings in macro lines
using semantic annotation macros.
.Pp
Examples:
.Dl ".Em italic , Sy bold , No and roman"
.Pp
.Bd -literal -offset indent -compact
\&.Sm off
\&.Cm :C No / Ar pattern No / Ar replacement No /
\&.Sm on
.Ed
.Pp
See also
.Sx \&Em ,
.Sx \&Li ,
and
.Sx \&Sy .
.Ss \&Ns
Suppress a space between the output of the preceding macro
and the following text or macro.
Following invocation, input is interpreted as normal text
just like after an
.Sx \&No
macro.
.Pp
This has no effect when invoked at the start of a macro line.
.Pp
Examples:
.Dl ".Ar name Ns = Ns Ar value"
.Dl ".Cm :M Ns Ar pattern"
.Dl ".Fl o Ns Ar output"
.Pp
See also
.Sx \&No
and
.Sx \&Sm .
.Ss \&Nx
Format the
.Nx
version provided as an argument, or a default value if
no argument is provided.
.Pp
Examples:
.Dl \&.Nx 5.01
.Dl \&.Nx
.Pp
See also
.Sx \&At ,
.Sx \&Bsx ,
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Fx ,
and
.Sx \&Ox .
.Ss \&Oc
Close multi-line
.Sx \&Oo
context.
.Ss \&Oo
Multi-line version of
.Sx \&Op .
.Pp
Examples:
.Bd -literal -offset indent -compact
\&.Oo
\&.Op Fl flag Ns Ar value
\&.Oc
.Ed
.Ss \&Op
Optional part of a command line.
Prints the argument(s) in brackets.
This is most often used in the
.Em SYNOPSIS
section of section 1 and 8 manual pages.
.Pp
Examples:
.Dl \&.Op \&Fl a \&Ar b
.Dl \&.Op \&Ar a | b
.Pp
See also
.Sx \&Oo .
.Ss \&Os
Operating system version for display in the page footer.
This is the mandatory third macro of
any
.Nm
file.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Os Op Ar system Op Ar version
.Pp
The optional
.Ar system
parameter specifies the relevant operating system or environment.
It is suggested to leave it unspecified, in which case
.Xr mandoc 1
uses its
.Fl Ios
argument or, if that isn't specified either,
.Fa sysname
and
.Fa release
as returned by
.Xr uname 3 .
.Pp
Examples:
.Dl \&.Os
.Dl \&.Os KTH/CSC/TCS
.Dl \&.Os BSD 4.3
.Pp
See also
.Sx \&Dd
and
.Sx \&Dt .
.Ss \&Ot
This macro is obsolete.
Use
.Sx \&Ft
instead; with
.Xr mandoc 1 ,
both have the same effect.
.Pp
Historical
.Nm
packages described it as
.Dq "old function type (FORTRAN)" .
.Ss \&Ox
Format the
.Ox
version provided as an argument, or a default value
if no argument is provided.
.Pp
Examples:
.Dl \&.Ox 4.5
.Dl \&.Ox
.Pp
See also
.Sx \&At ,
.Sx \&Bsx ,
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Fx ,
and
.Sx \&Nx .
.Ss \&Pa
An absolute or relative file system path, or a file or directory name.
If an argument is not provided, the character
.Sq \(ti
is used as a default.
.Pp
Examples:
.Dl \&.Pa /usr/bin/mandoc
.Dl \&.Pa /usr/share/man/man7/mdoc.7
.Pp
See also
.Sx \&Lk .
.Ss \&Pc
Close parenthesised context opened by
.Sx \&Po .
.Ss \&Pf
Removes the space between its argument and the following macro.
Its syntax is as follows:
.Pp
.D1 .Pf Ar prefix macro arguments ...
.Pp
This is equivalent to:
.Pp
.D1 .No \e& Ns Ar prefix No \&Ns Ar macro arguments ...
.Pp
The
.Ar prefix
argument is not parsed for macro names or delimiters,
but used verbatim as if it were escaped.
.Pp
Examples:
.Dl ".Pf $ Ar variable_name"
.Dl ".Pf . Ar macro_name"
.Dl ".Pf 0x Ar hex_digits"
.Pp
See also
.Sx \&Ns
and
.Sx \&Sm .
.Ss \&Po
Multi-line version of
.Sx \&Pq .
.Ss \&Pp
Break a paragraph.
This will assert vertical space between prior and subsequent macros
and/or text.
.Pp
Paragraph breaks are not needed before or after
.Sx \&Sh
or
.Sx \&Ss
macros or before displays
.Pq Sx \&Bd
or lists
.Pq Sx \&Bl
unless the
.Fl compact
flag is given.
.Ss \&Pq
Parenthesised enclosure.
.Pp
See also
.Sx \&Po .
.Ss \&Qc
Close quoted context opened by
.Sx \&Qo .
.Ss \&Ql
In-line literal display.
This can for example be used for complete command invocations and
for multi-word code fragments when more specific markup is not
appropriate and an indented display is not desired.
While
.Xr mandoc 1
always encloses the arguments in single quotes, other formatters
usually omit the quotes on non-terminal output devices when the
arguments have three or more characters.
.Pp
See also
.Sx \&Dl
and
.Sx \&Bd
.Fl literal .
.Ss \&Qo
Multi-line version of
.Sx \&Qq .
.Ss \&Qq
Encloses its arguments in
.Qq typewriter
double-quotes.
Consider using
.Sx \&Dq .
.Pp
See also
.Sx \&Dq ,
.Sx \&Sq ,
and
.Sx \&Qo .
.Ss \&Re
Close an
.Sx \&Rs
block.
Does not have any tail arguments.
.Ss \&Rs
Begin a bibliographic
.Pq Dq reference
block.
Does not have any head arguments.
The block macro may only contain
.Sx \&%A ,
.Sx \&%B ,
.Sx \&%C ,
.Sx \&%D ,
.Sx \&%I ,
.Sx \&%J ,
.Sx \&%N ,
.Sx \&%O ,
.Sx \&%P ,
.Sx \&%Q ,
.Sx \&%R ,
.Sx \&%T ,
.Sx \&%U ,
and
.Sx \&%V
child macros (at least one must be specified).
.Pp
Examples:
.Bd -literal -offset indent -compact
\&.Rs
\&.%A J. E. Hopcroft
\&.%A J. D. Ullman
\&.%B Introduction to Automata Theory, Languages, and Computation
\&.%I Addison-Wesley
\&.%C Reading, Massachusetts
\&.%D 1979
\&.Re
.Ed
.Pp
If an
.Sx \&Rs
block is used within a SEE ALSO section, a vertical space is asserted
before the rendered output, else the block continues on the current
line.
.Ss \&Rv
Insert a standard sentence regarding a function call's return value of 0
on success and \-1 on error, with the
.Va errno
libc global variable set on error.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Rv Fl std Op Ar function ...
.Pp
If
.Ar function
is not specified, the document's name set by
.Sx \&Nm
is used.
Multiple
.Ar function
arguments are treated as separate functions.
.Pp
See also
.Sx \&Ex .
.Ss \&Sc
Close single-quoted context opened by
.Sx \&So .
.Ss \&Sh
Begin a new section.
For a list of conventional manual sections, see
.Sx MANUAL STRUCTURE .
These sections should be used unless it's absolutely necessary that
custom sections be used.
.Pp
Section names should be unique so that they may be keyed by
.Sx \&Sx .
Although this macro is parsed, it should not consist of child node or it
may not be linked with
.Sx \&Sx .
.Pp
See also
.Sx \&Pp ,
.Sx \&Ss ,
and
.Sx \&Sx .
.Ss \&Sm
Switches the spacing mode for output generated from macros.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Sm Op Cm on | off
.Pp
By default, spacing is
.Cm on .
When switched
.Cm off ,
no white space is inserted between macro arguments and between the
output generated from adjacent macros, but text lines
still get normal spacing between words and sentences.
.Pp
When called without an argument, the
.Sx \&Sm
macro toggles the spacing mode.
Using this is not recommended because it makes the code harder to read.
.Ss \&So
Multi-line version of
.Sx \&Sq .
.Ss \&Sq
Encloses its arguments in
.Sq typewriter
single-quotes.
.Pp
See also
.Sx \&Dq ,
.Sx \&Qq ,
and
.Sx \&So .
.Ss \&Ss
Begin a new subsection.
Unlike with
.Sx \&Sh ,
there is no convention for the naming of subsections.
Except
.Em DESCRIPTION ,
the conventional sections described in
.Sx MANUAL STRUCTURE
rarely have subsections.
.Pp
Sub-section names should be unique so that they may be keyed by
.Sx \&Sx .
Although this macro is parsed, it should not consist of child node or it
may not be linked with
.Sx \&Sx .
.Pp
See also
.Sx \&Pp ,
.Sx \&Sh ,
and
.Sx \&Sx .
.Ss \&St
Replace an abbreviation for a standard with the full form.
The following standards are recognised.
Where multiple lines are given without a blank line in between,
they all refer to the same standard, and using the first form
is recommended.
.Bl -tag -width 1n
.It C language standards
.Pp
.Bl -tag -width "-p1003.1g-2000" -compact
.It \-ansiC
.St -ansiC
.It \-ansiC-89
.St -ansiC-89
.It \-isoC
.St -isoC
.It \-isoC-90
.St -isoC-90
.br
The original C standard.
.Pp
.It \-isoC-amd1
.St -isoC-amd1
.Pp
.It \-isoC-tcor1
.St -isoC-tcor1
.Pp
.It \-isoC-tcor2
.St -isoC-tcor2
.Pp
.It \-isoC-99
.St -isoC-99
.br
The second major version of the C language standard.
.Pp
.It \-isoC-2011
.St -isoC-2011
.br
The third major version of the C language standard.
.El
.It POSIX.1 before the Single UNIX Specification
.Pp
.Bl -tag -width "-p1003.1g-2000" -compact
.It \-p1003.1-88
.St -p1003.1-88
.It \-p1003.1
.St -p1003.1
.br
The original POSIX standard, based on ANSI C.
.Pp
.It \-p1003.1-90
.St -p1003.1-90
.It \-iso9945-1-90
.St -iso9945-1-90
.br
The first update of POSIX.1.
.Pp
.It \-p1003.1b-93
.St -p1003.1b-93
.It \-p1003.1b
.St -p1003.1b
.br
Real-time extensions.
.Pp
.It \-p1003.1c-95
.St -p1003.1c-95
.br
POSIX thread interfaces.
.Pp
.It \-p1003.1i-95
.St -p1003.1i-95
.br
Technical Corrigendum.
.Pp
.It \-p1003.1-96
.St -p1003.1-96
.It \-iso9945-1-96
.St -iso9945-1-96
.br
Includes POSIX.1-1990, 1b, 1c, and 1i.
.El
.It X/Open Portability Guide version 4 and related standards
.Pp
.Bl -tag -width "-p1003.1g-2000" -compact
.It \-xpg3
.St -xpg3
.br
An XPG4 precursor, published in 1989.
.Pp
.It \-p1003.2
.St -p1003.2
.It \-p1003.2-92
.St -p1003.2-92
.It \-iso9945-2-93
.St -iso9945-2-93
.br
An XCU4 precursor.
.Pp
.It \-p1003.2a-92
.St -p1003.2a-92
.br
Updates to POSIX.2.
.Pp
.It \-xpg4
.St -xpg4
.br
Based on POSIX.1 and POSIX.2, published in 1992.
.El
.It Single UNIX Specification version 1 and related standards
.Pp
.Bl -tag -width "-p1003.1g-2000" -compact
.It \-susv1
.St -susv1
.It \-xpg4.2
.St -xpg4.2
.br
This standard was published in 1994.
It was used as the basis for UNIX 95 certification.
The following three refer to parts of it.
.Pp
.It \-xsh4.2
.St -xsh4.2
.Pp
.It \-xcurses4.2
.St -xcurses4.2
.Pp
.It \-p1003.1g-2000
.St -p1003.1g-2000
.br
Networking APIs, including sockets.
.Pp
.It \-svid4
.St -svid4 ,
.br
Published in 1995.
.El
.It Single UNIX Specification version 2 and related standards
.Pp
.Bl -tag -width "-p1003.1g-2000" -compact
.It \-susv2
.St -susv2
This Standard was published in 1997
and is also called X/Open Portability Guide version 5.
It was used as the basis for UNIX 98 certification.
The following refer to parts of it.
.Pp
.It \-xbd5
.St -xbd5
.Pp
.It \-xsh5
.St -xsh5
.Pp
.It \-xcu5
.St -xcu5
.Pp
.It \-xns5
.St -xns5
.It \-xns5.2
.St -xns5.2
.El
.It Single UNIX Specification version 3
.Pp
.Bl -tag -width "-p1003.1-2001" -compact
.It \-p1003.1-2001
.St -p1003.1-2001
.It \-susv3
.St -susv3
.br
This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j.
It is also called X/Open Portability Guide version 6.
It is used as the basis for UNIX 03 certification.
.Pp
.It \-p1003.1-2004
.St -p1003.1-2004
.br
The second and last Technical Corrigendum.
.El
.It Single UNIX Specification version 4
.Pp
.Bl -tag -width "-p1003.1g-2000" -compact
.It \-p1003.1-2008
.St -p1003.1-2008
.It \-susv4
.St -susv4
.br
This standard is also called
X/Open Portability Guide version 7.
.El
.It Other standards
.Pp
.Bl -tag -width "-p1003.1g-2000" -compact
.It \-ieee754
.St -ieee754
.br
Floating-point arithmetic.
.Pp
.It \-iso8601
.St -iso8601
.br
Representation of dates and times, published in 1988.
.Pp
.It \-iso8802-3
.St -iso8802-3
.br
Ethernet local area networks.
.Pp
.It \-ieee1275-94
.St -ieee1275-94
.El
.El
.Ss \&Sx
Reference a section or subsection in the same manual page.
The referenced section or subsection name must be identical to the
enclosed argument, including whitespace.
.Pp
Examples:
.Dl \&.Sx MANUAL STRUCTURE
.Pp
See also
.Sx \&Sh
and
.Sx \&Ss .
.Ss \&Sy
Request a boldface font.
.Pp
This is most often used to indicate importance or seriousness (not to be
confused with stress emphasis, see
.Sx \&Em ) .
When none of the semantic macros fit, it is also adequate for syntax
elements that have to be given or that appear verbatim.
.Pp
Examples:
.Bd -literal -compact -offset indent
\&.Sy Warning :
If
\&.Sy s
appears in the owner permissions, set-user-ID mode is set.
This utility replaces the former
\&.Sy dumpdir
program.
.Ed
.Pp
See also
.Sx \&Bf ,
.Sx \&Em ,
.Sx \&Li ,
and
.Sx \&No .
.Ss \&Ta
Table cell separator in
.Sx \&Bl Fl column
lists; can only be used below
.Sx \&It .
.Ss \&Tn
Supported only for compatibility, do not use this in new manuals.
Even though the macro name
.Pq Dq tradename
suggests a semantic function, historic usage is inconsistent, mostly
using it as a presentation-level macro to request a small caps font.
.Ss \&Ud
Supported only for compatibility, do not use this in new manuals.
Prints out
.Dq currently under development.
.Ss \&Ux
Supported only for compatibility, do not use this in new manuals.
Prints out
.Dq Ux .
.Ss \&Va
A variable name.
.Pp
Examples:
.Dl \&.Va foo
.Dl \&.Va const char *bar ;
.Pp
For function arguments and parameters, use
.Sx \&Fa
instead.
For declarations of global variables in the
.Em SYNOPSIS
section, use
.Sx \&Vt .
.Ss \&Vt
A variable type.
.Pp
This is also used for indicating global variables in the
.Em SYNOPSIS
section, in which case a variable name is also specified.
Note that it accepts
.Sx Block partial-implicit
syntax when invoked as the first macro on an input line in the
.Em SYNOPSIS
section, else it accepts ordinary
.Sx In-line
syntax.
In the former case, this macro starts a new output line,
and a blank line is inserted in front if there is a preceding
function definition or include directive.
.Pp
Examples:
.Dl \&.Vt unsigned char
.Dl \&.Vt extern const char * const sys_signame[] \&;
.Pp
For parameters in function prototypes, use
.Sx \&Fa
instead, for function return types
.Sx \&Ft ,
and for variable names outside the
.Em SYNOPSIS
section
.Sx \&Va ,
even when including a type with the name.
See also
.Sx MANUAL STRUCTURE .
.Ss \&Xc
Close a scope opened by
.Sx \&Xo .
.Ss \&Xo
Extend the header of an
.Sx \&It
macro or the body of a partial-implicit block macro
beyond the end of the input line.
This macro originally existed to work around the 9-argument limit
of historic
.Xr roff 7 .
.Ss \&Xr
Link to another manual
.Pq Qq cross-reference .
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Xr Ar name section
.Pp
Cross reference the
.Ar name
and
.Ar section
number of another man page.
.Pp
Examples:
.Dl \&.Xr mandoc 1
.Dl \&.Xr mandoc 1 \&;
.Dl \&.Xr mandoc 1 \&Ns s behaviour
.Sh MACRO SYNTAX
The syntax of a macro depends on its classification.
In this section,
.Sq \-arg
refers to macro arguments, which may be followed by zero or more
.Sq parm
parameters;
.Sq \&Yo
opens the scope of a macro; and if specified,
.Sq \&Yc
closes it out.
.Pp
The
.Em Callable
column indicates that the macro may also be called by passing its name
as an argument to another macro.
For example,
.Sq \&.Op \&Fl O \&Ar file
produces
.Sq Op Fl O Ar file .
To prevent a macro call and render the macro name literally,
escape it by prepending a zero-width space,
.Sq \e& .
For example,
.Sq \&Op \e&Fl O
produces
.Sq Op \&Fl O .
If a macro is not callable but its name appears as an argument
to another macro, it is interpreted as opaque text.
For example,
.Sq \&.Fl \&Sh
produces
.Sq Fl \&Sh .
.Pp
The
.Em Parsed
column indicates whether the macro may call other macros by receiving
their names as arguments.
If a macro is not parsed but the name of another macro appears
as an argument, it is interpreted as opaque text.
.Pp
The
.Em Scope
column, if applicable, describes closure rules.
.Ss Block full-explicit
Multi-line scope closed by an explicit closing macro.
All macros contains bodies; only
.Sx \&Bf
and
.Pq optionally
.Sx \&Bl
contain a head.
.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
\(lBbody...\(rB
\&.Yc
.Ed
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
.It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
.It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
.It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek
.It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El
.It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd
.It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf
.It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk
.It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl
.El
.Ss Block full-implicit
Multi-line scope closed by end-of-file or implicitly by another macro.
All macros have bodies; some
.Po
.Sx \&It Fl bullet ,
.Fl hyphen ,
.Fl dash ,
.Fl enum ,
.Fl item
.Pc
don't have heads; only one
.Po
.Sx \&It
in
.Sx \&Bl Fl column
.Pc
has multiple heads.
.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
\(lBbody...\(rB
.Ed
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
.It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
.It Sx \&Sh Ta \&No Ta Yes Ta closed by Sx \&Sh
.It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss
.El
.Pp
Note that the
.Sx \&Nm
macro is a
.Sx Block full-implicit
macro only when invoked as the first macro
in a
.Em SYNOPSIS
section line, else it is
.Sx In-line .
.Ss Block partial-explicit
Like block full-explicit, but also with single-line scope.
Each has at least a body and, in limited circumstances, a head
.Po
.Sx \&Fo ,
.Sx \&Eo
.Pc
and/or tail
.Pq Sx \&Ec .
.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
\(lBbody...\(rB
\&.Yc \(lBtail...\(rB
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
\(lBbody...\(rB \&Yc \(lBtail...\(rB
.Ed
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
.It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
.It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo
.It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc
.It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro
.It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc
.It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do
.It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc
.It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo
.It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec
.It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo
.It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc
.It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo
.It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc
.It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po
.It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc
.It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo
.It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc
.It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
.It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
.It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So
.It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc
.It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo
.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc
.El
.Ss Block partial-implicit
Like block full-implicit, but with single-line scope closed by the
end of the line.
.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
.Ed
.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed
.It Sx \&Aq Ta Yes Ta Yes
.It Sx \&Bq Ta Yes Ta Yes
.It Sx \&Brq Ta Yes Ta Yes
.It Sx \&D1 Ta \&No Ta \&Yes
.It Sx \&Dl Ta \&No Ta Yes
.It Sx \&Dq Ta Yes Ta Yes
.It Sx \&En Ta Yes Ta Yes
.It Sx \&Op Ta Yes Ta Yes
.It Sx \&Pq Ta Yes Ta Yes
.It Sx \&Ql Ta Yes Ta Yes
.It Sx \&Qq Ta Yes Ta Yes
.It Sx \&Sq Ta Yes Ta Yes
.It Sx \&Vt Ta Yes Ta Yes
.El
.Pp
Note that the
.Sx \&Vt
macro is a
.Sx Block partial-implicit
only when invoked as the first macro
in a
.Em SYNOPSIS
section line, else it is
.Sx In-line .
.Ss Special block macro
The
.Sx \&Ta
macro can only be used below
.Sx \&It
in
.Sx \&Bl Fl column
lists.
It delimits blocks representing table cells;
these blocks have bodies, but no heads.
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
.It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It
.El
.Ss In-line
Closed by the end of the line, fixed argument lengths,
and/or subsequent macros.
In-line macros have only text children.
If a number (or inequality) of arguments is
.Pq n ,
then the macro accepts an arbitrary number of arguments.
.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
.Ed
.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
.It Sx \&%A Ta \&No Ta \&No Ta >0
.It Sx \&%B Ta \&No Ta \&No Ta >0
.It Sx \&%C Ta \&No Ta \&No Ta >0
.It Sx \&%D Ta \&No Ta \&No Ta >0
.It Sx \&%I Ta \&No Ta \&No Ta >0
.It Sx \&%J Ta \&No Ta \&No Ta >0
.It Sx \&%N Ta \&No Ta \&No Ta >0
.It Sx \&%O Ta \&No Ta \&No Ta >0
.It Sx \&%P Ta \&No Ta \&No Ta >0
.It Sx \&%Q Ta \&No Ta \&No Ta >0
.It Sx \&%R Ta \&No Ta \&No Ta >0
.It Sx \&%T Ta \&No Ta \&No Ta >0
.It Sx \&%U Ta \&No Ta \&No Ta >0
.It Sx \&%V Ta \&No Ta \&No Ta >0
.It Sx \&Ad Ta Yes Ta Yes Ta >0
.It Sx \&An Ta Yes Ta Yes Ta >0
.It Sx \&Ap Ta Yes Ta Yes Ta 0
.It Sx \&Ar Ta Yes Ta Yes Ta n
.It Sx \&At Ta Yes Ta Yes Ta 1
.It Sx \&Bsx Ta Yes Ta Yes Ta n
.It Sx \&Bt Ta \&No Ta \&No Ta 0
.It Sx \&Bx Ta Yes Ta Yes Ta n
.It Sx \&Cd Ta Yes Ta Yes Ta >0
.It Sx \&Cm Ta Yes Ta Yes Ta >0
.It Sx \&Db Ta \&No Ta \&No Ta 1
.It Sx \&Dd Ta \&No Ta \&No Ta n
.It Sx \&Dt Ta \&No Ta \&No Ta n
.It Sx \&Dv Ta Yes Ta Yes Ta >0
.It Sx \&Dx Ta Yes Ta Yes Ta n
.It Sx \&Em Ta Yes Ta Yes Ta >0
.It Sx \&Er Ta Yes Ta Yes Ta >0
.It Sx \&Es Ta Yes Ta Yes Ta 2
.It Sx \&Ev Ta Yes Ta Yes Ta >0
.It Sx \&Ex Ta \&No Ta \&No Ta n
.It Sx \&Fa Ta Yes Ta Yes Ta >0
.It Sx \&Fd Ta \&No Ta \&No Ta >0
.It Sx \&Fl Ta Yes Ta Yes Ta n
.It Sx \&Fn Ta Yes Ta Yes Ta >0
.It Sx \&Fr Ta Yes Ta Yes Ta >0
.It Sx \&Ft Ta Yes Ta Yes Ta >0
.It Sx \&Fx Ta Yes Ta Yes Ta n
.It Sx \&Hf Ta \&No Ta \&No Ta n
.It Sx \&Ic Ta Yes Ta Yes Ta >0
.It Sx \&In Ta \&No Ta \&No Ta 1
.It Sx \&Lb Ta \&No Ta \&No Ta 1
.It Sx \&Li Ta Yes Ta Yes Ta >0
.It Sx \&Lk Ta Yes Ta Yes Ta >0
.It Sx \&Lp Ta \&No Ta \&No Ta 0
.It Sx \&Ms Ta Yes Ta Yes Ta >0
.It Sx \&Mt Ta Yes Ta Yes Ta >0
.It Sx \&Nm Ta Yes Ta Yes Ta n
.It Sx \&No Ta Yes Ta Yes Ta 0
.It Sx \&Ns Ta Yes Ta Yes Ta 0
.It Sx \&Nx Ta Yes Ta Yes Ta n
.It Sx \&Os Ta \&No Ta \&No Ta n
.It Sx \&Ot Ta Yes Ta Yes Ta >0
.It Sx \&Ox Ta Yes Ta Yes Ta n
.It Sx \&Pa Ta Yes Ta Yes Ta n
.It Sx \&Pf Ta Yes Ta Yes Ta 1
.It Sx \&Pp Ta \&No Ta \&No Ta 0
.It Sx \&Rv Ta \&No Ta \&No Ta n
.It Sx \&Sm Ta \&No Ta \&No Ta <2
.It Sx \&St Ta \&No Ta Yes Ta 1
.It Sx \&Sx Ta Yes Ta Yes Ta >0
.It Sx \&Sy Ta Yes Ta Yes Ta >0
.It Sx \&Tn Ta Yes Ta Yes Ta >0
.It Sx \&Ud Ta \&No Ta \&No Ta 0
.It Sx \&Ux Ta Yes Ta Yes Ta n
.It Sx \&Va Ta Yes Ta Yes Ta n
.It Sx \&Vt Ta Yes Ta Yes Ta >0
.It Sx \&Xr Ta Yes Ta Yes Ta 2
.El
.Ss Delimiters
When a macro argument consists of one single input character
considered as a delimiter, the argument gets special handling.
This does not apply when delimiters appear in arguments containing
more than one character.
Consequently, to prevent special handling and just handle it
like any other argument, a delimiter can be escaped by prepending
a zero-width space
.Pq Sq \e& .
In text lines, delimiters never need escaping, but may be used
as normal punctuation.
.Pp
For many macros, when the leading arguments are opening delimiters,
these delimiters are put before the macro scope,
and when the trailing arguments are closing delimiters,
these delimiters are put after the macro scope.
Spacing is suppressed after opening delimiters
and before closing delimiters.
For example,
.Pp
.D1 Pf \. \&Aq "( [ word ] ) ."
.Pp
renders as:
.Pp
.D1 Aq ( [ word ] ) .
.Pp
Opening delimiters are:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It \&(
left parenthesis
.It \&[
left bracket
.El
.Pp
Closing delimiters are:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It \&.
period
.It \&,
comma
.It \&:
colon
.It \&;
semicolon
.It \&)
right parenthesis
.It \&]
right bracket
.It \&?
question mark
.It \&!
exclamation mark
.El
.Pp
Note that even a period preceded by a backslash
.Pq Sq \e.\&
gets this special handling; use
.Sq \e&.
to prevent that.
.Pp
Many in-line macros interrupt their scope when they encounter
delimiters, and resume their scope when more arguments follow that
are not delimiters.
For example,
.Pp
.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e"
.Pp
renders as:
.Pp
.D1 Fl a ( b | c \*(Ba d ) e
.Pp
This applies to both opening and closing delimiters,
and also to the middle delimiter, which does not suppress spacing:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It \&|
vertical bar
.El
.Pp
As a special case, the predefined string \e*(Ba is handled and rendered
in the same way as a plain
.Sq \&|
character.
Using this predefined string is not recommended in new manuals.
.Ss Font handling
In
.Nm
documents, usage of semantic markup is recommended in order to have
proper fonts automatically selected; only when no fitting semantic markup
is available, consider falling back to
.Sx Physical markup
macros.
Whenever any
.Nm
macro switches the
.Xr roff 7
font mode, it will automatically restore the previous font when exiting
its scope.
Manually switching the font using the
.Xr roff 7
.Ql \ef
font escape sequences is never required.
.Sh COMPATIBILITY
This section provides an incomplete list of compatibility issues
between mandoc and GNU troff
.Pq Qq groff .
.Pp
The following problematic behaviour is found in groff:
.Pp
.Bl -dash -compact
.It
.Sx \&Dd
with non-standard arguments behaves very strangely.
When there are three arguments, they are printed verbatim.
Any other number of arguments is replaced by the current date,
but without any arguments the string
.Dq Epoch
is printed.
.It
.Sx \&Lk
only accepts a single link-name argument; the remainder is misformatted.
.It
.Sx \&Pa
does not format its arguments when used in the FILES section under
certain list types.
.It
.Sx \&Ta
can only be called by other macros, but not at the beginning of a line.
.It
.Sx \&%C
is not implemented (up to and including groff-1.22.2).
.It
.Sq \ef
.Pq font face
and
.Sq \eF
.Pq font family face
.Sx Text Decoration
escapes behave irregularly when specified within line-macro scopes.
.It
Negative scaling units return to prior lines.
Instead, mandoc truncates them to zero.
.El
.Pp
The following features are unimplemented in mandoc:
.Pp
.Bl -dash -compact
.It
.Sx \&Bd
.Fl file Ar file
is unsupported for security reasons.
.It
.Sx \&Bd
.Fl filled
does not adjust the right margin, but is an alias for
.Sx \&Bd
.Fl ragged .
.It
.Sx \&Bd
.Fl literal
does not use a literal font, but is an alias for
.Sx \&Bd
.Fl unfilled .
.It
.Sx \&Bd
.Fl offset Cm center
and
.Fl offset Cm right
don't work.
Groff does not implement centered and flush-right rendering either,
but produces large indentations.
.El
.Sh SEE ALSO
.Xr man 1 ,
.Xr mandoc 1 ,
.Xr eqn 7 ,
.Xr man 7 ,
.Xr mandoc_char 7 ,
.Xr roff 7 ,
.Xr tbl 7
.Pp
The web page
.Lk http://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language"
provides a few tutorial-style pages for beginners, an extensive style
guide for advanced authors, and an alphabetic index helping to choose
the best macros for various kinds of content.
.Sh HISTORY
The
.Nm
language first appeared as a troff macro package in
.Bx 4.4 .
It was later significantly updated by Werner Lemberg and Ruslan Ermilov
in groff-1.17.
The standalone implementation that is part of the
.Xr mandoc 1
utility written by Kristaps Dzonsons appeared in
.Ox 4.6 .
.Sh AUTHORS
The
.Nm
reference was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
mandoc-1.14.3/mandoc_malloc.3 0100644 0002007 0000011 00000010734 13141336266 0015337 0 ustar 00schwarze wsrc .\" $Id: mandoc_malloc.3,v 1.2 2016/07/07 19:19:01 schwarze Exp $
.\"
.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: July 7 2016 $
.Dt MANDOC_MALLOC 3
.Os
.Sh NAME
.Nm mandoc_malloc ,
.Nm mandoc_realloc ,
.Nm mandoc_reallocarray ,
.Nm mandoc_calloc ,
.Nm mandoc_strdup ,
.Nm mandoc_strndup ,
.Nm mandoc_asprintf
.Nd memory allocation function wrappers used in the mandoc library
.Sh SYNOPSIS
.In sys/types.h
.In mandoc_aux.h
.Ft "void *"
.Fo mandoc_malloc
.Fa "size_t size"
.Fc
.Ft "void *"
.Fo mandoc_realloc
.Fa "void *ptr"
.Fa "size_t size"
.Fc
.Ft "void *"
.Fo mandoc_reallocarray
.Fa "void *ptr"
.Fa "size_t nmemb"
.Fa "size_t size"
.Fc
.Ft "void *"
.Fo mandoc_calloc
.Fa "size_t nmemb"
.Fa "size_t size"
.Fc
.Ft "char *"
.Fo mandoc_strdup
.Fa "const char *s"
.Fc
.Ft "char *"
.Fo mandoc_strndup
.Fa "const char *s"
.Fa "size_t maxlen"
.Fc
.Ft int
.Fo mandoc_asprintf
.Fa "char **ret"
.Fa "const char *format"
.Fa "..."
.Fc
.Sh DESCRIPTION
These functions call the libc functions of the same names, passing
through their return values when successful.
In case of failure, they do not return, but instead call
.Xr err 3 .
They can be used both internally by any code in the mandoc libraries
and externally by programs using that library, for example
.Xr mandoc 1 ,
.Xr man 1 ,
.Xr apropos 1 ,
.Xr makewhatis 8 ,
and
.Xr man.cgi 8 .
.Pp
The function
.Fn mandoc_malloc
allocates one new object, leaving the memory uninitialized.
The functions
.Fn mandoc_realloc
and
.Fn mandoc_reallocarray
change the size of an existing object or array, possibly moving it.
When shrinking the size, existing data is truncated; when growing,
the additional memory is not initialized.
The function
.Fn mandoc_calloc
allocates a new array, initializing it to zero.
.Pp
The argument
.Fa size
is the size of each object.
The argument
.Fa nmemb
is the new number of objects in the array.
The argument
.Fa ptr
is a pointer to the existing object or array to be resized; if it is
.Dv NULL ,
a new object or array is allocated.
.Pp
The functions
.Fn mandoc_strdup
and
.Fn mandoc_strndup
copy a string into newly allocated memory.
For
.Fn mandoc_strdup ,
the string pointed to by
.Fa s
needs to be NUL-terminated.
For
.Fn mandoc_strndup ,
at most
.Fa maxlen
bytes are copied.
The function
.Fn mandoc_asprintf
writes output formatted according to
.Fa format
into newly allocated memory and returns a pointer to the result in
.Fa ret .
For all three string functions, the result is always NUL-terminated.
.Pp
When the objects and strings are no longer needed,
the pointers returned by these functions can be passed to
.Xr free 3 .
.Sh RETURN VALUES
The function
.Fn mandoc_asprintf
always returns the number of characters written, excluding the
final NUL byte.
It never returns -1.
.Pp
The other functions always return a valid pointer; they never return
.Dv NULL .
.Sh FILES
These functions are implemented in
.Pa mandoc_aux.c .
.Sh SEE ALSO
.Xr asprintf 3 ,
.Xr err 3 ,
.Xr malloc 3 ,
.Xr strdup 3
.Sh STANDARDS
The functions
.Fn malloc ,
.Fn realloc ,
and
.Fn calloc
are required by
.St -ansiC .
The functions
.Fn strdup
and
.Fn strndup
are required by
.St -p1003.1-2008 .
The function
.Fn asprintf
is a widespread extension that first appeared in the GNU C library.
.Pp
The function
.Fn reallocarray
is an extension that first appeared in
.Ox 5.6 .
If it is not provided by the operating system, the mandoc build system
uses a bundled portable implementation.
.Sh HISTORY
The functions
.Fn mandoc_malloc ,
.Fn mandoc_realloc ,
.Fn mandoc_calloc ,
and
.Fn mandoc_strdup
have been available since mandoc 1.9.12,
.Fn mandoc_strndup
since 1.11.5,
and
.Fn mandoc_asprintf
and
.Fn mandoc_reallocarray
since 1.12.4 and 1.13.0.
.Sh AUTHORS
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
.An Ingo Schwarze Aq Mt schwarze@openbsd.org
mandoc-1.14.3/mandoc_ohash.h 0100644 0002007 0000011 00000001754 13141336266 0015261 0 ustar 00schwarze wsrc /* $Id: mandoc_ohash.h,v 1.2 2015/11/07 14:01:16 schwarze Exp $ */
/*
* Copyright (c) 2015 Ingo Schwarze <schwarze@openbsd.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#if HAVE_OHASH
#include <ohash.h>
#else
#include "compat_ohash.h"
#endif
void mandoc_ohash_init(struct ohash *, unsigned int, ptrdiff_t);
mandoc-1.14.3/mandoc_xr.h 0100644 0002007 0000011 00000002257 13141336266 0014607 0 ustar 00schwarze wsrc /* $Id: mandoc_xr.h,v 1.3 2017/07/02 21:18:29 schwarze Exp $ */
/*
* Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
struct mandoc_xr {
struct mandoc_xr *next;
char *sec;
char *name;
int line; /* Or -1 for this page's own names. */
int pos;
int count;
char hashkey[];
};
void mandoc_xr_reset(void);
int mandoc_xr_add(const char *, const char *, int, int);
struct mandoc_xr *mandoc_xr_get(void);
void mandoc_xr_free(void);
mandoc-1.14.3/mandocd.8 0100644 0002007 0000011 00000011133 13141336266 0014153 0 ustar 00schwarze wsrc .\" $Id: mandocd.8,v 1.2 2017/03/18 19:56:01 schwarze Exp $
.\"
.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: March 18 2017 $
.Dt MANDOCD 8
.Os
.Sh NAME
.Nm mandocd
.Nd server process to format manual pages in batch mode
.Sh SYNOPSIS
.Nm mandocd
.Op Fl I Cm os Ns = Ns Ar name
.Op Fl T Ar output
.Ar socket_fd
.Sh DESCRIPTION
The
.Nm
utility formats many manual pages without requiring
.Xr fork 2
and
.Xr exec 3
overhead in between.
It does not require listing all the manuals to be formatted on the
command line, and it supports writing each formatted manual to its
own file descriptor.
.Pp
This server requires that a connected UNIX domain
.Xr socket 2
is already present at
.Xr exec 3
time.
Consequently, it cannot be started from the
.Xr sh 1
command line because the shell cannot supply such a socket.
Typically, the socket is created by the parent process using
.Xr socketpair 2
before calling
.Xr fork 2
and
.Xr exec 3
on
.Nm .
The parent process will pass the file descriptor number as an argument to
.Xr exec 3 ,
formatted as a decimal ASCII-encoded integer.
See
.Xr catman 8
for a typical implementation of a parent process.
.Pp
.Nm
loops reading one-byte messages with
.Xr recvmsg 2
from the file descriptor number
.Ar socket_fd .
It ignores the byte read and only uses the out-of-band auxiliary
.Vt struct cmsghdr
control data, typically supplied by the calling process using
.Xr CMSG_FIRSTHDR 3 .
The parent process is expected to pass three file descriptors
with each dummy byte.
The first one is used for
.Xr mdoc 7
or
.Xr man 7
input, the second one for formatted output, and the third one
for error output.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl I Cm os Ns = Ns Ar name
Override the default operating system
.Ar name
for the
.Xr mdoc 7
.Ic \&Os
and for the
.Xr man 7
.Ic TH
macro.
.It Fl T Ar output
Output format.
The
.Ar output
argument can be
.Cm ascii ,
.Cm utf8 ,
or
.Cm html ;
see
.Xr mandoc 1 .
In
.Cm html
output mode, the
.Cm fragment
output option is implied.
Other output options are not supported.
.El
.Pp
After exhausting one input file descriptor, all three file descriptors
are closed before reading the next dummy byte and control message.
.Pp
When a zero-byte message is read, when the
.Ar socket_fd
is closed by the parent process,
or when an error occurs,
.Nm
exits.
.Sh EXIT STATUS
.Ex -std
.Pp
A zero-byte message or a closed
.Ar socket_fd
is considered success.
Possible errors include:
.Bl -bullet
.It
missing, invalid, or excessive
.Xr exec 3
arguments
.It
.Xr recvmsg 2
failure, for example due to
.Er EMSGSIZE
.It
missing or unexpected control data, in particular a
.Fa cmsg_level
in the
.Vt struct cmsghdr
that differs from
.Dv SOL_SOCKET ,
a
.Fa cmsg_type
that differs from
.Dv SCM_RIGHTS ,
or a
.Fa cmsg_len
that is not three times the size of an
.Vt int
.It
invalid file descriptors passed in the
.Xr CMSG_DATA 3
.It
resource exhaustion, in particular
.Xr dup 2
or
.Xr malloc 3
failure
.El
.Pp
Except for memory exhaustion and similar system-level failures,
parsing and formatting errors do not cause
.Nm
to return an error exit status.
Even after severe parsing errors,
.Nm
will simply accept and process the next input file descriptor.
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr mandoc 3 ,
.Xr catman 8
.Sh HISTORY
The
.Nm
utility appeared in version 1.14.1 or the
.Sy mandoc
toolkit.
.Sh AUTHORS
.An -nosplit
The concept was designed and implemented by
.An Michael Stapelberg Aq Mt stapelberg@debian.org .
The
.Xr mandoc 3
glue needed to make it a stand-alone process was added by
.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
.Sh CAVEATS
If the parsed manual pages contain
.Xr roff 7
.Pf . Ic so
requests,
.Nm
needs to be started with the current working directory set to the
root of the manual page tree.
Avoid starting it in directories that contain secret files in any
subdirectories, in particular in the user starting it has read
access to these secret files.
mandoc-1.14.3/mansearch.3 0100644 0002007 0000011 00000006416 13141336266 0014512 0 ustar 00schwarze wsrc .\" $Id: mansearch.3,v 1.5 2017/03/30 22:22:05 schwarze Exp $
.\"
.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: March 30 2017 $
.Dt MANSEARCH 3
.Os
.Sh NAME
.Nm mansearch
.Nd search manual page databases
.Sh SYNOPSIS
.In stdint.h
.In manconf.h
.In mansearch.h
.Ft int
.Fo mansearch
.Fa "const struct mansearch *search"
.Fa "const struct manpaths *paths"
.Fa "int argc"
.Fa "char *argv[]"
.Fa "struct manpage **res"
.Fa "size_t *sz"
.Fc
.Sh DESCRIPTION
The
.Fn mansearch
function returns information about manuals matching a search query from a
.Xr mandoc.db 5
database.
.Pp
The query arguments are as follows:
.Bl -tag -width Ds
.It Fa "const struct mansearch *search"
Search options, defined in
.In mansearch.h .
.It Fa "const struct manpaths *paths"
Directories to be searched, defined in
.In manconf.h .
.It Fa "int argc" , "char *argv[]"
Search criteria, usually taken from the command line.
.El
.Pp
The output arguments are as follows:
.Bl -tag -width Ds
.It Fa "struct manpage **res"
Returns a pointer to an array of result structures defined in
.In mansearch.h .
The user is expected to call
.Xr free 3
on the
.Va file ,
.Va names ,
and
.Va output
fields of all structures, as well as the
.Fa res
array itself.
.It Fa "size_t *sz"
Returns the number of result structures contained in
.Fa res .
.El
.Sh IMPLEMENTATION NOTES
For each manual page tree, the search is done in two steps.
In the first step, a list of pages matching the search criteria is built.
In the second step, the requested information about these pages is
retrieved from the database and assembled into the
.Fa res
array.
.Pp
All function mentioned here are defined in the file
.Pa mansearch.c .
.Ss Finding matches
Command line parsing is done by the function
.Fn exprcomp
building a singly linked list of
.Vt expr
structures, using the helper functions
.Fn expr_and
and
.Fn exprterm .
.Ss Assembling the results
The names, sections, and architectures of the manuals found
are assembled into the
.Va names
field of the result structure by the function
.Fn buildnames .
.Sh FILES
.Bl -tag -width mandoc.db -compact
.It Pa mandoc.db
The manual page database.
.El
.Sh SEE ALSO
.Xr apropos 1 ,
.Xr mandoc.db 5 ,
.Xr makewhatis 8
.Sh HISTORY
The
.Fn mansearch
subsystem first appeared in
.Ox 5.6 .
.Sh AUTHORS
.An -nosplit
A module to search manual page databases was first written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
in 2011, at first using the Berkeley DB;
he rewrote it for SQLite3 in 2012, and
.An Ingo Schwarze Aq Mt schwarze@openbsd.org
removed the dependency on SQLite3 in 2016.
mandoc-1.14.3/mansearch.h 0100644 0002007 0000011 00000010042 13141336266 0014565 0 ustar 00schwarze wsrc /* $Id: mansearch.h,v 1.28 2017/04/17 20:05:08 schwarze Exp $ */
/*
* Copyright (c) 2012 Kristaps Dzonsons <kristaps@bsd.lv>
* Copyright (c) 2013, 2014, 2016, 2017 Ingo Schwarze <schwarze@openbsd.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#define MANDOC_DB "mandoc.db"
#define MANDOCDB_MAGIC 0x3a7d0cdb
#define MANDOCDB_VERSION 1
#define MACRO_MAX 36
#define KEY_arch 0
#define KEY_sec 1
#define KEY_Nm 38
#define KEY_Nd 39
#define KEY_MAX 40
#define TYPE_arch 0x0000000000000001ULL
#define TYPE_sec 0x0000000000000002ULL
#define TYPE_Xr 0x0000000000000004ULL
#define TYPE_Ar 0x0000000000000008ULL
#define TYPE_Fa 0x0000000000000010ULL
#define TYPE_Fl 0x0000000000000020ULL
#define TYPE_Dv 0x0000000000000040ULL
#define TYPE_Fn 0x0000000000000080ULL
#define TYPE_Ic 0x0000000000000100ULL
#define TYPE_Pa 0x0000000000000200ULL
#define TYPE_Cm 0x0000000000000400ULL
#define TYPE_Li 0x0000000000000800ULL
#define TYPE_Em 0x0000000000001000ULL
#define TYPE_Cd 0x0000000000002000ULL
#define TYPE_Va 0x0000000000004000ULL
#define TYPE_Ft 0x0000000000008000ULL
#define TYPE_Tn 0x0000000000010000ULL
#define TYPE_Er 0x0000000000020000ULL
#define TYPE_Ev 0x0000000000040000ULL
#define TYPE_Sy 0x0000000000080000ULL
#define TYPE_Sh 0x0000000000100000ULL
#define TYPE_In 0x0000000000200000ULL
#define TYPE_Ss 0x0000000000400000ULL
#define TYPE_Ox 0x0000000000800000ULL
#define TYPE_An 0x0000000001000000ULL
#define TYPE_Mt 0x0000000002000000ULL
#define TYPE_St 0x0000000004000000ULL
#define TYPE_Bx 0x0000000008000000ULL
#define TYPE_At 0x0000000010000000ULL
#define TYPE_Nx 0x0000000020000000ULL
#define TYPE_Fx 0x0000000040000000ULL
#define TYPE_Lk 0x0000000080000000ULL
#define TYPE_Ms 0x0000000100000000ULL
#define TYPE_Bsx 0x0000000200000000ULL
#define TYPE_Dx 0x0000000400000000ULL
#define TYPE_Rs 0x0000000800000000ULL
#define TYPE_Vt 0x0000001000000000ULL
#define TYPE_Lb 0x0000002000000000ULL
#define TYPE_Nm 0x0000004000000000ULL
#define TYPE_Nd 0x0000008000000000ULL
#define NAME_SYN 0x0000004000000001ULL
#define NAME_FIRST 0x0000004000000004ULL
#define NAME_TITLE 0x0000004000000006ULL
#define NAME_HEAD 0x0000004000000008ULL
#define NAME_FILE 0x0000004000000010ULL
#define NAME_MASK 0x000000000000001fULL
enum form {
FORM_SRC = 1, /* Format is mdoc(7) or man(7). */
FORM_CAT, /* Manual page is preformatted. */
FORM_NONE /* Format is unknown. */
};
enum argmode {
ARG_FILE = 0,
ARG_NAME,
ARG_WORD,
ARG_EXPR
};
struct manpage {
char *file; /* to be prefixed by manpath */
char *names; /* a list of names with sections */
char *output; /* user-defined additional output */
size_t ipath; /* number of the manpath */
uint64_t bits; /* name type mask */
int sec; /* section number, 10 means invalid */
enum form form;
};
struct mansearch {
const char *arch; /* architecture/NULL */
const char *sec; /* mansection/NULL */
const char *outkey; /* show content of this macro */
enum argmode argmode; /* interpretation of arguments */
int firstmatch; /* first matching database only */
};
struct manpaths;
int mansearch(const struct mansearch *cfg, /* options */
const struct manpaths *paths, /* manpaths */
int argc, /* size of argv */
char *argv[], /* search terms */
struct manpage **res, /* results */
size_t *ressz); /* results returned */
void mansearch_free(struct manpage *, size_t);
mandoc-1.14.3/mchars_alloc.3 0100644 0002007 0000011 00000012362 13141336266 0015175 0 ustar 00schwarze wsrc .\" $Id: mchars_alloc.3,v 1.4 2016/07/07 19:19:01 schwarze Exp $
.\"
.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: July 7 2016 $
.Dt MCHARS_ALLOC 3
.Os
.Sh NAME
.Nm mchars_alloc ,
.Nm mchars_free ,
.Nm mchars_num2char ,
.Nm mchars_num2uc ,
.Nm mchars_spec2cp ,
.Nm mchars_spec2str ,
.Nm mchars_uc2str
.Nd character table for mandoc
.Sh SYNOPSIS
.In sys/types.h
.In mandoc.h
.Ft void
.Fn mchars_alloc void
.Ft void
.Fn mchars_free void
.Ft char
.Fo mchars_num2char
.Fa "const char *decimal"
.Fa "size_t sz"
.Fc
.Ft int
.Fo mchars_num2uc
.Fa "const char *hexadecimal"
.Fa "size_t sz"
.Fc
.Ft int
.Fo mchars_spec2cp
.Fa "const char *name"
.Fa "size_t sz"
.Fc
.Ft "const char *"
.Fo mchars_spec2str
.Fa "const char *name"
.Fa "size_t sz"
.Fa "size_t *rsz"
.Fc
.Ft "const char *"
.Fn mchars_uc2str "int codepoint"
.Sh DESCRIPTION
These functions translate Unicode character numbers and
.Xr roff 7
character names into glyphs.
See
.Xr mandoc_char 7
for a list of
.Xr roff 7
special characters.
These functions are intended for external use by programs formatting
.Xr mdoc 7
and
.Xr man 7
pages for output, for example the
.Xr mandoc 1
output formatter modules and
.Xr makewhatis 8 .
The
.Fa decimal ,
.Fa hexadecimal ,
.Fa name ,
and
.Fa size
input arguments are usually obtained from the
.Xr mandoc_escape 3
parser function.
.Pp
The function
.Fn mchars_num2char
converts a
.Fa decimal
string representation of a character number consisting of
.Fa sz
digits into a printable ASCII character.
If the input string is non-numeric or does not represent a printable
ASCII character, the NUL character
.Pq Sq \e0
is returned.
For example, the
.Xr mandoc 1
.Fl Tascii ,
.Fl Tutf8 ,
and
.Fl Thtml
output modules use this function to render
.Xr roff 7
.Ic \eN
escape sequences.
.Pp
The function
.Fn mchars_num2uc
converts a
.Fa hexadecimal
string representation of a Unicode codepoint consisting of
.Fa sz
digits into an integer representation.
If the input string is non-numeric or represents an ASCII character,
the NUL character
.Pq Sq \e0
is returned.
For example, the
.Xr mandoc 1
.Fl Tutf8
and
.Fl Thtml
output modules use this function to render
.Xr roff 7
.Ic \e[u Ns Ar XXXX Ns Ic \&]
and
.Ic \eC\(aqu Ns Ar XXXX Ns Ic \(aq
escape sequences.
.Pp
The function
.Fn mchars_alloc
initializes a static
.Vt "struct ohash"
object for subsequent use by the following two lookup functions.
When no longer needed, this object can be destroyed with
.Fn mchars_free .
.Pp
The function
.Fn mchars_spec2cp
looks up a
.Xr roff 7
special character
.Fa name
consisting of
.Fa sz
characters and returns the corresponding Unicode codepoint.
If the
.Ar name
is not recognized, \-1 is returned.
For example, the
.Xr mandoc 1
.Fl Tutf8
and
.Fl Thtml
output modules use this function to render
.Xr roff 7
.Ic \e[ Ns Ar name Ns Ic \&]
and
.Ic \eC\(aq Ns Ar name Ns Ic \(aq
escape sequences.
.Pp
The function
.Fn mchars_spec2str
looks up a
.Xr roff 7
special character
.Fa name
consisting of
.Fa sz
characters and returns an ASCII string representation.
The length of the representation is returned in
.Fa rsz .
In many cases, the meaning of such ASCII representations
is not quite obvious, so using
.Xr roff 7
special characters in documents intended for ASCII rendering
is usually a bad idea.
If the
.Ar name
is not recognized,
.Dv NULL
is returned.
For example,
.Xr makewhatis 8
and the
.Xr mandoc 1
.Fl Tascii
output module use this function to render
.Xr roff 7
.Ic \e[ Ns Ar name Ns Ic \&]
and
.Ic \eC\(aq Ns Ar name Ns Ic \(aq
escape sequences.
.Pp
The function
.Fn mchars_uc2str
performs a reverse lookup of the Unicode
.Fa codepoint
and returns an ASCII string representation, or the string
.Qq <?>
if none is available.
.Sh FILES
These funtions are implemented in the file
.Pa chars.c .
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr mandoc_escape 3 ,
.Xr ohash_init 3 ,
.Xr mandoc_char 7 ,
.Xr roff 7
.Sh HISTORY
These functions and their predecessors have been available since the
following mandoc versions:
.Bl -column "mchars_num2char()" "1.11.3" "chars_num2char()" "1.10.10"
.It Sy function Ta since Ta Sy predecessor Ta since
.It Fn mchars_alloc Ta 1.11.3 Ta Fn ascii2htab Ta 1.5.3
.It Fn mchars_free Ta 1.11.2 Ta Fn asciifree Ta 1.6.0
.It Fn mchars_num2char Ta 1.11.2 Ta Fn chars_num2char Ta 1.10.10
.It Fn mchars_num2uc Ta 1.11.3 Ta \(em Ta \(em
.It Fn mchars_spec2cp Ta 1.11.2 Ta Fn chars_spec2cp Ta 1.10.5
.It Fn mchars_spec2str Ta 1.11.2 Ta Fn a2ascii Ta 1.5.3
.It Fn mchars_uc2str Ta 1.13.2 Ta \(em Ta \(em
.El
.Sh AUTHORS
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
.An Ingo Schwarze Aq Mt schwarze@openbsd.org
mandoc-1.14.3/mdoc.h 0100644 0002007 0000011 00000007661 13141336266 0013563 0 ustar 00schwarze wsrc /* $Id: mdoc.h,v 1.145 2017/04/24 23:06:18 schwarze Exp $ */
/*
* Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
* Copyright (c) 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
enum mdocargt {
MDOC_Split, /* -split */
MDOC_Nosplit, /* -nospli */
MDOC_Ragged, /* -ragged */
MDOC_Unfilled, /* -unfilled */
MDOC_Literal, /* -literal */
MDOC_File, /* -file */
MDOC_Offset, /* -offset */
MDOC_Bullet, /* -bullet */
MDOC_Dash, /* -dash */
MDOC_Hyphen, /* -hyphen */
MDOC_Item, /* -item */
MDOC_Enum, /* -enum */
MDOC_Tag, /* -tag */
MDOC_Diag, /* -diag */
MDOC_Hang, /* -hang */
MDOC_Ohang, /* -ohang */
MDOC_Inset, /* -inset */
MDOC_Column, /* -column */
MDOC_Width, /* -width */
MDOC_Compact, /* -compact */
MDOC_Std, /* -std */
MDOC_Filled, /* -filled */
MDOC_Words, /* -words */
MDOC_Emphasis, /* -emphasis */
MDOC_Symbolic, /* -symbolic */
MDOC_Nested, /* -nested */
MDOC_Centred, /* -centered */
MDOC_ARG_MAX
};
/*
* An argument to a macro (multiple values = `-column xxx yyy').
*/
struct mdoc_argv {
enum mdocargt arg; /* type of argument */
int line;
int pos;
size_t sz; /* elements in "value" */
char **value; /* argument strings */
};
/*
* Reference-counted macro arguments. These are refcounted because
* blocks have multiple instances of the same arguments spread across
* the HEAD, BODY, TAIL, and BLOCK node types.
*/
struct mdoc_arg {
size_t argc;
struct mdoc_argv *argv;
unsigned int refcnt;
};
enum mdoc_list {
LIST__NONE = 0,
LIST_bullet, /* -bullet */
LIST_column, /* -column */
LIST_dash, /* -dash */
LIST_diag, /* -diag */
LIST_enum, /* -enum */
LIST_hang, /* -hang */
LIST_hyphen, /* -hyphen */
LIST_inset, /* -inset */
LIST_item, /* -item */
LIST_ohang, /* -ohang */
LIST_tag, /* -tag */
LIST_MAX
};
enum mdoc_disp {
DISP__NONE = 0,
DISP_centered, /* -centered */
DISP_ragged, /* -ragged */
DISP_unfilled, /* -unfilled */
DISP_filled, /* -filled */
DISP_literal /* -literal */
};
enum mdoc_auth {
AUTH__NONE = 0,
AUTH_split, /* -split */
AUTH_nosplit /* -nosplit */
};
enum mdoc_font {
FONT__NONE = 0,
FONT_Em, /* Em, -emphasis */
FONT_Li, /* Li, -literal */
FONT_Sy /* Sy, -symbolic */
};
struct mdoc_bd {
const char *offs; /* -offset */
enum mdoc_disp type; /* -ragged, etc. */
int comp; /* -compact */
};
struct mdoc_bl {
const char *width; /* -width */
const char *offs; /* -offset */
enum mdoc_list type; /* -tag, -enum, etc. */
int comp; /* -compact */
size_t ncols; /* -column arg count */
const char **cols; /* -column val ptr */
int count; /* -enum counter */
};
struct mdoc_bf {
enum mdoc_font font; /* font */
};
struct mdoc_an {
enum mdoc_auth auth; /* -split, etc. */
};
struct mdoc_rs {
int quote_T; /* whether to quote %T */
};
/*
* Consists of normalised node arguments. These should be used instead
* of iterating through the mdoc_arg pointers of a node: defaults are
* provided, etc.
*/
union mdoc_data {
struct mdoc_an An;
struct mdoc_bd Bd;
struct mdoc_bf Bf;
struct mdoc_bl Bl;
struct roff_node *Es;
struct mdoc_rs Rs;
};
/* Names of macro args. Index is enum mdocargt. */
extern const char *const *mdoc_argnames;
void mdoc_validate(struct roff_man *);
mandoc-1.14.3/msec.in 0100644 0002007 0000011 00000002544 13141336266 0013742 0 ustar 00schwarze wsrc /* $Id: msec.in,v 1.8 2017/06/24 17:37:06 schwarze Exp $ */
/*
* Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
/*
* These are all possible manual-section macros and what they correspond
* to when rendered as the volume title.
*
* Be sure to escape strings.
*/
LINE("1", "General Commands Manual")
LINE("2", "System Calls Manual")
LINE("3", "Library Functions Manual")
LINE("3p", "Perl Library Manual")
LINE("4", "Device Drivers Manual")
LINE("5", "File Formats Manual")
LINE("6", "Games Manual")
LINE("7", "Miscellaneous Information Manual")
LINE("8", "System Manager\'s Manual")
LINE("9", "Kernel Developer\'s Manual")
mandoc-1.14.3/out.h 0100644 0002007 0000011 00000004506 13141336266 0013443 0 ustar 00schwarze wsrc /* $Id: out.h,v 1.31 2017/06/27 18:25:02 schwarze Exp $ */
/*
* Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
* Copyright (c) 2014, 2017 Ingo Schwarze <schwarze@openbsd.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
enum roffscale {
SCALE_CM, /* centimeters (c) */
SCALE_IN, /* inches (i) */
SCALE_PC, /* pica (P) */
SCALE_PT, /* points (p) */
SCALE_EM, /* ems (m) */
SCALE_MM, /* mini-ems (M) */
SCALE_EN, /* ens (n) */
SCALE_BU, /* default horizontal (u) */
SCALE_VS, /* default vertical (v) */
SCALE_FS, /* syn. for u (f) */
SCALE_MAX
};
struct roffcol {
size_t width; /* width of cell */
size_t decimal; /* decimal position in cell */
size_t spacing; /* spacing after the column */
int flags; /* layout flags, see tbl_cell */
};
struct roffsu {
enum roffscale unit;
double scale;
};
typedef size_t (*tbl_sulen)(const struct roffsu *, void *);
typedef size_t (*tbl_strlen)(const char *, void *);
typedef size_t (*tbl_len)(size_t, void *);
struct rofftbl {
tbl_sulen sulen; /* calculate scaling unit length */
tbl_strlen slen; /* calculate string length */
tbl_len len; /* produce width of empty space */
struct roffcol *cols; /* master column specifiers */
void *arg; /* passed to sulen, slen, and len */
};
#define SCALE_VS_INIT(p, v) \
do { (p)->unit = SCALE_VS; \
(p)->scale = (v); } \
while (/* CONSTCOND */ 0)
#define SCALE_HS_INIT(p, v) \
do { (p)->unit = SCALE_EN; \
(p)->scale = (v); } \
while (/* CONSTCOND */ 0)
struct tbl_span;
const char *a2roffsu(const char *, struct roffsu *, enum roffscale);
void tblcalc(struct rofftbl *tbl,
const struct tbl_span *, size_t, size_t);
mandoc-1.14.3/predefs.in 0100644 0002007 0000011 00000004063 13141336266 0014441 0 ustar 00schwarze wsrc /* $Id: predefs.in,v 1.4 2012/07/18 10:39:19 schwarze Exp $ */
/*
* Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
/*
* The predefined-string translation tables. Each corresponds to a
* predefined strings from (e.g.) tmac/mdoc/doc-nroff. The left-hand
* side corresponds to the input sequence (\*x, \*(xx and so on). The
* right-hand side is what's produced by libroff.
*
* XXX - C-escape strings!
* XXX - update PREDEF_MAX in roff.c if adding more!
*/
PREDEF("Am", "&")
PREDEF("Ba", "\\fR|\\fP")
PREDEF("Ge", "\\(>=")
PREDEF("Gt", ">")
PREDEF("If", "infinity")
PREDEF("Le", "\\(<=")
PREDEF("Lq", "\\(lq")
PREDEF("Lt", "<")
PREDEF("Na", "NaN")
PREDEF("Ne", "\\(!=")
PREDEF("Pi", "pi")
PREDEF("Pm", "\\(+-")
PREDEF("Rq", "\\(rq")
PREDEF("left-bracket", "[")
PREDEF("left-parenthesis", "(")
PREDEF("lp", "(")
PREDEF("left-singlequote", "\\(oq")
PREDEF("q", "\\(dq")
PREDEF("quote-left", "\\(oq")
PREDEF("quote-right", "\\(cq")
PREDEF("R", "\\(rg")
PREDEF("right-bracket", "]")
PREDEF("right-parenthesis", ")")
PREDEF("rp", ")")
PREDEF("right-singlequote", "\\(cq")
PREDEF("Tm", "(Tm)")
PREDEF("Px", "POSIX")
PREDEF("Ai", "ANSI")
PREDEF("\'", "\\\'")
PREDEF("aa", "\\(aa")
PREDEF("ga", "\\(ga")
PREDEF("`", "\\`")
PREDEF("lq", "\\(lq")
PREDEF("rq", "\\(rq")
PREDEF("ua", "\\(ua")
PREDEF("va", "\\(va")
PREDEF("<=", "\\(<=")
PREDEF(">=", "\\(>=")
mandoc-1.14.3/roff.7 0100644 0002007 0000011 00000163715 13141336266 0013517 0 ustar 00schwarze wsrc .\" $Id: roff.7,v 1.94 2017/07/05 12:25:17 schwarze Exp $
.\"
.\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010,2011,2013-2015,2017 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: July 5 2017 $
.Dt ROFF 7
.Os
.Sh NAME
.Nm roff
.Nd roff language reference for mandoc
.Sh DESCRIPTION
The
.Nm roff
language is a general purpose text formatting language.
Since traditional implementations of the
.Xr mdoc 7
and
.Xr man 7
manual formatting languages are based on it,
many real-world manuals use small numbers of
.Nm
requests and escape sequences intermixed with their
.Xr mdoc 7
or
.Xr man 7
code.
To properly format such manuals, the
.Xr mandoc 1
utility supports a tiny subset of
.Nm
requests and escapes.
Only these requests and escapes supported by
.Xr mandoc 1
are documented in the present manual,
together with the basic language syntax shared by
.Nm ,
.Xr mdoc 7 ,
and
.Xr man 7 .
For complete
.Nm
manuals, consult the
.Sx SEE ALSO
section.
.Pp
Input lines beginning with the control character
.Sq \&.
are parsed for requests and macros.
Such lines are called
.Dq request lines
or
.Dq macro lines ,
respectively.
Requests change the processing state and manipulate the formatting;
some macros also define the document structure and produce formatted
output.
The single quote
.Pq Qq \(aq
is accepted as an alternative control character,
treated by
.Xr mandoc 1
just like
.Ql \&.
.Pp
Lines not beginning with control characters are called
.Dq text lines .
They provide free-form text to be printed; the formatting of the text
depends on the respective processing context.
.Sh LANGUAGE SYNTAX
.Nm
documents may contain only graphable 7-bit ASCII characters, the space
character, and, in certain circumstances, the tab character.
The backslash character
.Sq \e
indicates the start of an escape sequence, used for example for
.Sx Comments ,
.Sx Special Characters ,
.Sx Predefined Strings ,
and
user-defined strings defined using the
.Sx ds
request.
For a listing of escape sequences, consult the
.Sx ESCAPE SEQUENCE REFERENCE
below.
.Ss Comments
Text following an escaped double-quote
.Sq \e\(dq ,
whether in a request, macro, or text line, is ignored to the end of the line.
A request line beginning with a control character and comment escape
.Sq \&.\e\(dq
is also ignored.
Furthermore, request lines with only a control character and optional
trailing whitespace are stripped from input.
.Pp
Examples:
.Bd -literal -offset indent -compact
\&.\e\(dq This is a comment line.
\&.\e\(dq The next line is ignored:
\&.
\&.Sh EXAMPLES \e\(dq This is a comment, too.
\&example text \e\(dq And so is this.
.Ed
.Ss Special Characters
Special characters are used to encode special glyphs and are rendered
differently across output media.
They may occur in request, macro, and text lines.
Sequences begin with the escape character
.Sq \e
followed by either an open-parenthesis
.Sq \&(
for two-character sequences; an open-bracket
.Sq \&[
for n-character sequences (terminated at a close-bracket
.Sq \&] ) ;
or a single one character sequence.
.Pp
Examples:
.Bl -tag -width Ds -offset indent -compact
.It Li \e(em
Two-letter em dash escape.
.It Li \ee
One-letter backslash escape.
.El
.Pp
See
.Xr mandoc_char 7
for a complete list.
.Ss Text Decoration
Terms may be text-decorated using the
.Sq \ef
escape followed by an indicator: B (bold), I (italic), R (regular), or P
(revert to previous mode).
A numerical representation 3, 2, or 1 (bold, italic, and regular,
respectively) may be used instead.
The indicator or numerical representative may be preceded by C
(constant-width), which is ignored.
.Pp
The two-character indicator
.Sq BI
requests a font that is both bold and italic.
It may not be portable to old roff implementations.
.Pp
Examples:
.Bl -tag -width Ds -offset indent -compact
.It Li \efBbold\efR
Write in \fBbold\fP, then switch to regular font mode.
.It Li \efIitalic\efP
Write in \fIitalic\fP, then return to previous font mode.
.It Li \ef(BIbold italic\efP
Write in \f(BIbold italic\fP, then return to previous font mode.
.El
.Pp
Text decoration is
.Em not
recommended for
.Xr mdoc 7 ,
which encourages semantic annotation.
.Ss Predefined Strings
Predefined strings, like
.Sx Special Characters ,
mark special output glyphs.
Predefined strings are escaped with the slash-asterisk,
.Sq \e* :
single-character
.Sq \e*X ,
two-character
.Sq \e*(XX ,
and N-character
.Sq \e* Ns Bq N .
.Pp
Examples:
.Bl -tag -width Ds -offset indent -compact
.It Li \e*(Am
Two-letter ampersand predefined string.
.It Li \e*q
One-letter double-quote predefined string.
.El
.Pp
Predefined strings are not recommended for use,
as they differ across implementations.
Those supported by
.Xr mandoc 1
are listed in
.Xr mandoc_char 7 .
Manuals using these predefined strings are almost certainly not portable.
.Ss Whitespace
Whitespace consists of the space character.
In text lines, whitespace is preserved within a line.
In request and macro lines, whitespace delimits arguments and is discarded.
.Pp
Unescaped trailing spaces are stripped from text line input unless in a
literal context.
In general, trailing whitespace on any input line is discouraged for
reasons of portability.
In the rare case that a blank character is needed at the end of an
input line, it may be forced by
.Sq \e\ \e& .
.Pp
Literal space characters can be produced in the output
using escape sequences.
In macro lines, they can also be included in arguments using quotation; see
.Sx MACRO SYNTAX
for details.
.Pp
Blank text lines, which may include whitespace, are only permitted
within literal contexts.
If the first character of a text line is a space, that line is printed
with a leading newline.
.Ss Scaling Widths
Many requests and macros support scaled widths for their arguments.
The syntax for a scaled width is
.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
where a decimal must be preceded or followed by at least one digit.
Negative numbers, while accepted, are truncated to zero.
.Pp
The following scaling units are accepted:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It c
centimetre
.It i
inch
.It P
pica (~1/6 inch)
.It p
point (~1/72 inch)
.It f
scale
.Sq u
by 65536
.It v
default vertical span
.It m
width of rendered
.Sq m
.Pq em
character
.It n
width of rendered
.Sq n
.Pq en
character
.It u
default horizontal span for the terminal
.It M
mini-em (~1/100 em)
.El
.Pp
Using anything other than
.Sq m ,
.Sq n ,
or
.Sq v
is necessarily non-portable across output media.
See
.Sx COMPATIBILITY .
.Pp
If a scaling unit is not provided, the numerical value is interpreted
under the default rules of
.Sq v
for vertical spaces and
.Sq u
for horizontal ones.
.Pp
Examples:
.Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact
.It Li \&.Bl -tag -width 2i
two-inch tagged list indentation in
.Xr mdoc 7
.It Li \&.HP 2i
two-inch tagged list indentation in
.Xr man 7
.It Li \&.sp 2v
two vertical spaces
.El
.Ss Sentence Spacing
Each sentence should terminate at the end of an input line.
By doing this, a formatter will be able to apply the proper amount of
spacing after the end of sentence (unescaped) period, exclamation mark,
or question mark followed by zero or more non-sentence closing
delimiters
.Po
.Sq \&) ,
.Sq \&] ,
.Sq \&' ,
.Sq \&"
.Pc .
.Pp
The proper spacing is also intelligently preserved if a sentence ends at
the boundary of a macro line.
.Pp
Examples:
.Bd -literal -offset indent -compact
Do not end sentences mid-line like this. Instead,
end a sentence like this.
A macro would end like this:
\&.Xr mandoc 1 \&.
.Ed
.Sh REQUEST SYNTAX
A request or macro line consists of:
.Pp
.Bl -enum -compact
.It
the control character
.Sq \&.
or
.Sq \(aq
at the beginning of the line,
.It
optionally an arbitrary amount of whitespace,
.It
the name of the request or the macro, which is one word of arbitrary
length, terminated by whitespace,
.It
and zero or more arguments delimited by whitespace.
.El
.Pp
Thus, the following request lines are all equivalent:
.Bd -literal -offset indent
\&.ig end
\&.ig end
\&. ig end
.Ed
.Sh MACRO SYNTAX
Macros are provided by the
.Xr mdoc 7
and
.Xr man 7
languages and can be defined by the
.Sx \&de
request.
When called, they follow the same syntax as requests, except that
macro arguments may optionally be quoted by enclosing them
in double quote characters
.Pq Sq \(dq .
Quoted text, even if it contains whitespace or would cause
a macro invocation when unquoted, is always considered literal text.
Inside quoted text, pairs of double quote characters
.Pq Sq Qq
resolve to single double quote characters.
.Pp
To be recognised as the beginning of a quoted argument, the opening
quote character must be preceded by a space character.
A quoted argument extends to the next double quote character that is not
part of a pair, or to the end of the input line, whichever comes earlier.
Leaving out the terminating double quote character at the end of the line
is discouraged.
For clarity, if more arguments follow on the same input line,
it is recommended to follow the terminating double quote character
by a space character; in case the next character after the terminating
double quote character is anything else, it is regarded as the beginning
of the next, unquoted argument.
.Pp
Both in quoted and unquoted arguments, pairs of backslashes
.Pq Sq \e\e
resolve to single backslashes.
In unquoted arguments, space characters can alternatively be included
by preceding them with a backslash
.Pq Sq \e\~ ,
but quoting is usually better for clarity.
.Pp
Examples:
.Bl -tag -width Ds -offset indent -compact
.It Li .Fn strlen \(dqconst char *s\(dq
Group arguments
.Qq const char *s
into one function argument.
If unspecified,
.Qq const ,
.Qq char ,
and
.Qq *s
would be considered separate arguments.
.It Li .Op \(dqFl a\(dq
Consider
.Qq \&Fl a
as literal text instead of a flag macro.
.El
.Sh REQUEST REFERENCE
The
.Xr mandoc 1
.Nm
parser recognises the following requests.
For requests marked as "ignored" or "unsupported", any arguments are
ignored, and the number of arguments is not checked.
.Bl -tag -width Ds
.It Ic \&ab Op Ar message
Abort processing.
Currently unsupported.
.It Ic \&ad Op Cm b | c | l | n | r
Set line adjustment mode for subsequent text.
Currently ignored.
.It Ic \&af Ar registername format
Assign an output format to a number register.
Currently ignored.
.It Ic \&aln Ar newname oldname
Create an alias for a number register.
Currently unsupported.
.It Ic \&als Ar newname oldname
Create an alias for a request, string, macro, or diversion.
.It Ic \&am Ar macroname Op Ar endmacro
Append to a macro definition.
The syntax of this request is the same as that of
.Ic \&de .
.It Ic \&am1 Ar macroname Op Ar endmacro
Append to a macro definition, switching roff compatibility mode off
during macro execution (groff extension).
The syntax of this request is the same as that of
.Ic \&de1 .
Since
.Xr mandoc 1
does not implement
.Nm
compatibility mode at all, it handles this request as an alias for
.Ic \&am .
.It Ic \&ami Ar macrostring Op Ar endstring
Append to a macro definition, specifying the macro name indirectly
(groff extension).
The syntax of this request is the same as that of
.Ic \&dei .
.It Ic \&ami1 Ar macrostring Op Ar endstring
Append to a macro definition, specifying the macro name indirectly
and switching roff compatibility mode off during macro execution
(groff extension).
The syntax of this request is the same as that of
.Ic \&dei1 .
Since
.Xr mandoc 1
does not implement
.Nm
compatibility mode at all, it handles this request as an alias for
.Ic \&ami .
.It Ic \&as Ar stringname Op Ar string
Append to a user-defined string.
The syntax of this request is the same as that of
.Sx \&ds .
If a user-defined string with the specified name does not yet exist,
it is set to the empty string before appending.
.It Ic \&as1 Ar stringname Op Ar string
Append to a user-defined string, switching roff compatibility mode off
during macro execution (groff extension).
The syntax of this request is the same as that of
.Ic \&ds1 .
Since
.Xr mandoc 1
does not implement
.Nm
compatibility mode at all, it handles this request as an alias for
.Ic \&as .
.It Ic \&asciify Ar divname
Fully unformat a diversion.
Currently unsupported.
.It Ic \&backtrace
Print a backtrace of the input stack.
This is a groff extension and currently ignored.
.It Ic \&bd Ar font Oo Ar curfont Oc Op Ar offset
Artificially embolden by repeated printing with small shifts.
Currently ignored.
.It Ic \&bleedat Ar left top width height
Set the BleedBox page parameter for PDF generation.
This is a Heirloom extension and currently ignored.
.It Ic \&blm Ar macroname
Set a blank line trap.
Currently unsupported.
.It Ic \&box Ar divname
Begin a diversion without including a partially filled line.
Currently unsupported.
.It Ic \&boxa Ar divname
Add to a diversion without including a partially filled line.
Currently unsupported.
.It Ic \&bp Oo Cm + Ns | Ns Cm - Oc Ns Ar pagenumber
Begin a new page.
Currently ignored.
.It Ic \&BP Ar source height width position offset flags label
Define a frame and place a picture in it.
This is a Heirloom extension and currently unsupported.
.It Ic \&br
Break the output line.
.It Ic \&break
Break out of a
.Ic \&while
loop.
Currently unsupported.
.It Ic \&breakchar Ar char ...
Optional line break characters.
This is a Heirloom extension and currently ignored.
.It Ic \&brnl Ar N
Break output line after the next
.Ar N
input lines.
This is a Heirloom extension and currently ignored.
.It Ic \&brp
Break and spread output line.
Currently, this is implemented as an alias for
.Ic \&br .
.It Ic \&brpnl Ar N
Break and spread output line after the next
.Ar N
input lines.
This is a Heirloom extension and currently ignored.
.It Ic \&c2 Op Ar char
Change the no-break control character.
Currently unsupported.
.It Ic \&cc Op Ar char
Change the control character.
If
.Ar char
is not specified, the control character is reset to
.Sq \&. .
Trailing characters are ignored.
.It Ic \&ce Op Ar N
Center the next
.Ar N
input lines without filling.
.Ar N
defaults to 1.
An argument of 0 or less ends centering.
Currently, high level macros abort centering.
.It Ic \&cf Ar filename
Output the contents of a file.
Ignored because insecure.
.It Ic \&cflags Ar flags char ...
Set character flags.
This is a groff extension and currently ignored.
.It Ic \&ch Ar macroname Op Ar dist
Change a trap location.
Currently ignored.
.It Ic \&char Ar glyphname Op Ar string
Define a new glyph.
Currently unsupported.
.It Ic \&chop Ar stringname
Remove the last character from a macro, string, or diversion.
Currently unsupported.
.It Ic \&class Ar classname char ...
Define a character class.
This is a groff extension and currently ignored.
.It Ic \&close Ar streamname
Close an open file.
Ignored because insecure.
.It Ic \&CL Ar color text
Print text in color.
This is a Heirloom extension and currently unsupported.
.It Ic \&color Op Cm 1 | 0
Activate or deactivate colors.
This is a groff extension and currently ignored.
.It Ic \&composite Ar from to
Define a name component for composite glyph names.
This is a groff extension and currently unsupported.
.It Ic \&continue
Immediately start the next iteration of a
.Ic \&while
loop.
Currently unsupported.
.It Ic \&cp Op Cm 1 | 0
Switch
.Nm
compatibility mode on or off.
Currently ignored.
.It Ic \&cropat Ar left top width height
Set the CropBox page parameter for PDF generation.
This is a Heirloom extension and currently ignored.
.It Ic \&cs Ar font Op Ar width Op Ar emsize
Constant character spacing mode.
Currently ignored.
.It Ic \&cu Op Ar N
Underline next
.Ar N
input lines including whitespace.
Currently ignored.
.It Ic \&da Ar divname
Append to a diversion.
Currently unsupported.
.It Ic \&dch Ar macroname Op Ar dist
Change a trap location in the current diversion.
This is a Heirloom extension and currently unsupported.
.It Ic \&de Ar macroname Op Ar endmacro
Define a
.Nm
macro.
Its syntax can be either
.Bd -literal -offset indent
.Pf . Ic \&de Ar macroname
.Ar definition
\&..
.Ed
.Pp
or
.Bd -literal -offset indent
.Pf . Ic \&de Ar macroname Ar endmacro
.Ar definition
.Pf . Ar endmacro
.Ed
.Pp
Both forms define or redefine the macro
.Ar macroname
to represent the
.Ar definition ,
which may consist of one or more input lines, including the newline
characters terminating each line, optionally containing calls to
.Nm
requests,
.Nm
macros or high-level macros like
.Xr man 7
or
.Xr mdoc 7
macros, whichever applies to the document in question.
.Pp
Specifying a custom
.Ar endmacro
macro works in the same way as for
.Ic \&ig ;
namely, the call to
.Sq Pf . Ar endmacro
first ends the
.Ar definition ,
and after that, it is also evaluated as a
.Nm
request or
.Nm
macro, but not as a high-level macro.
.Pp
The macro can be invoked later using the syntax
.Pp
.D1 Pf . Ar macroname Op Ar argument Op Ar argument ...
.Pp
Regarding argument parsing, see
.Sx MACRO SYNTAX
above.
.Pp
The line invoking the macro will be replaced
in the input stream by the
.Ar definition ,
replacing all occurrences of
.No \e\e$ Ns Ar N ,
where
.Ar N
is a digit, by the
.Ar N Ns th Ar argument .
For example,
.Bd -literal -offset indent
\&.de ZN
\efI\e^\e\e$1\e^\efP\e\e$2
\&..
\&.ZN XtFree .
.Ed
.Pp
produces
.Pp
.D1 \efI\e^XtFree\e^\efP.
.Pp
in the input stream, and thus in the output: \fI\^XtFree\^\fP.
Each occurrence of \e\e$* is replaced with all the arguments,
joined together with single blank characters.
.Pp
Since macros and user-defined strings share a common string table,
defining a macro
.Ar macroname
clobbers the user-defined string
.Ar macroname ,
and the
.Ar definition
can also be printed using the
.Sq \e*
string interpolation syntax described below
.Ic ds ,
but this is rarely useful because every macro definition contains at least
one explicit newline character.
.Pp
In order to prevent endless recursion, both groff and
.Xr mandoc 1
limit the stack depth for expanding macros and strings
to a large, but finite number, and
.Xr mandoc 1
also limits the length of the expanded input line.
Do not rely on the exact values of these limits.
.It Ic \&de1 Ar macroname Op Ar endmacro
Define a
.Nm
macro that will be executed with
.Nm
compatibility mode switched off during macro execution.
This is a groff extension.
Since
.Xr mandoc 1
does not implement
.Nm
compatibility mode at all, it handles this request as an alias for
.Ic \&de .
.It Ic \&defcolor Ar newname scheme component ...
Define a color name.
This is a groff extension and currently ignored.
.It Ic \&dei Ar macrostring Op Ar endstring
Define a
.Nm
macro, specifying the macro name indirectly (groff extension).
The syntax of this request is the same as that of
.Ic \&de .
The effect is the same as:
.Pp
.D1 Pf . Cm \&de No \e* Ns Bo Ar macrostring Bc Op \e* Ns Bq Ar endstring
.It Ic \&dei1 Ar macrostring Op Ar endstring
Define a
.Nm
macro that will be executed with
.Nm
compatibility mode switched off during macro execution,
specifying the macro name indirectly (groff extension).
Since
.Xr mandoc 1
does not implement
.Nm
compatibility mode at all, it handles this request as an alias for
.Ic \&dei .
.It Ic \&device Ar string ...
.It Ic \&devicem Ar stringname
These two requests only make sense with the groff-specific intermediate
output format and are unsupported.
.It Ic \&di Ar divname
Begin a diversion.
Currently unsupported.
.It Ic \&do Ar command Op Ar argument ...
Execute
.Nm
request or macro line with compatibility mode disabled.
Currently unsupported.
.It Ic \&ds Ar stringname Op Oo \(dq Oc Ns Ar string
Define a user-defined string.
The
.Ar stringname
and
.Ar string
arguments are space-separated.
If the
.Ar string
begins with a double-quote character, that character will not be part
of the string.
All remaining characters on the input line form the
.Ar string ,
including whitespace and double-quote characters, even trailing ones.
.Pp
The
.Ar string
can be interpolated into subsequent text by using
.No \e* Ns Bq Ar stringname
for a
.Ar stringname
of arbitrary length, or \e*(NN or \e*N if the length of
.Ar stringname
is two or one characters, respectively.
Interpolation can be prevented by escaping the leading backslash;
that is, an asterisk preceded by an even number of backslashes
does not trigger string interpolation.
.Pp
Since user-defined strings and macros share a common string table,
defining a string
.Ar stringname
clobbers the macro
.Ar stringname ,
and the
.Ar stringname
used for defining a string can also be invoked as a macro,
in which case the following input line will be appended to the
.Ar string ,
forming a new input line passed to the
.Nm
parser.
For example,
.Bd -literal -offset indent
\&.ds badidea .S
\&.badidea
H SYNOPSIS
.Ed
.Pp
invokes the
.Ic SH
macro when used in a
.Xr man 7
document.
Such abuse is of course strongly discouraged.
.It Ic \&ds1 Ar stringname Op Oo \(dq Oc Ns Ar string
Define a user-defined string that will be expanded with
.Nm
compatibility mode switched off during string expansion.
This is a groff extension.
Since
.Xr mandoc 1
does not implement
.Nm
compatibility mode at all, it handles this request as an alias for
.Ic \&ds .
.It Ic \&dwh Ar dist macroname
Set a location trap in the current diversion.
This is a Heirloom extension and currently unsupported.
.It Ic \&dt Op Ar dist macroname
Set a trap within a diversion.
Currently unsupported.
.It Ic \&ec Op Ar char
Enable the escape mechanism and change the escape character.
The
.Ar char
argument defaults to the backslash
.Pq Sq \e .
.It Ic \&ecr
Restore the escape character.
Currently unsupported.
.It Ic \&ecs
Save the escape character.
Currently unsupported.
.It Ic \&el Ar body
The
.Dq else
half of an if/else conditional.
Pops a result off the stack of conditional evaluations pushed by
.Ic \&ie
and uses it as its conditional.
If no stack entries are present (e.g., due to no prior
.Ic \&ie
calls)
then false is assumed.
The syntax of this request is similar to
.Ic \&if
except that the conditional is missing.
.It Ic \&em Ar macroname
Set a trap at the end of input.
Currently unsupported.
.It Ic \&EN
End an equation block.
See
.Ic \&EQ .
.It Ic \&eo
Disable the escape mechanism completely.
.It Ic \&EP
End a picture started by
.Ic \&BP .
This is a Heirloom extension and currently unsupported.
.It Ic \&EQ
Begin an equation block.
See
.Xr eqn 7
for a description of the equation language.
.It Ic \&errprint Ar message
Print a string like an error message.
This is a Heirloom extension and currently ignored.
.It Ic \&ev Op Ar envname
Switch to another environment.
Currently unsupported.
.It Ic \&evc Op Ar envname
Copy an environment into the current environment.
Currently unsupported.
.It Ic \&ex
Abort processing and exit.
Currently unsupported.
.It Ic \&fallback Ar curfont font ...
Select the fallback sequence for a font.
This is a Heirloom extension and currently ignored.
.It Ic \&fam Op Ar familyname
Change the font family.
This is a groff extension and currently ignored.
.It Ic \&fc Op Ar delimchar Op Ar padchar
Define a delimiting and a padding character for fields.
Currently unsupported.
.It Ic \&fchar Ar glyphname Op Ar string
Define a fallback glyph.
Currently unsupported.
.It Ic \&fcolor Ar colorname
Set the fill color for \eD objects.
This is a groff extension and currently ignored.
.It Ic \&fdeferlig Ar font string ...
Defer ligature building.
This is a Heirloom extension and currently ignored.
.It Ic \&feature Cm + Ns | Ns Cm - Ns Ar name
Enable or disable an OpenType feature.
This is a Heirloom extension and currently ignored.
.It Ic \&fi
Switch to fill mode.
See
.Xr man 7 .
Ignored in
.Xr mdoc 7 .
.It Ic \&fkern Ar font minkern
Control the use of kerning tables for a font.
This is a Heirloom extension and currently ignored.
.It Ic \&fl
Flush output.
Currently ignored.
.It Ic \&flig Ar font string char ...
Define ligatures.
This is a Heirloom extension and currently ignored.
.It Ic \&fp Ar position font Op Ar filename
Assign font position.
Currently ignored.
.It Ic \&fps Ar mapname ...
Mount a font with a special character map.
This is a Heirloom extension and currently ignored.
.It Ic \&fschar Ar font glyphname Op Ar string
Define a font-specific fallback glyph.
This is a groff extension and currently unsupported.
.It Ic \&fspacewidth Ar font Op Ar afmunits
Set a font-specific width for the space character.
This is a Heirloom extension and currently ignored.
.It Ic \&fspecial Ar curfont Op Ar font ...
Conditionally define a special font.
This is a groff extension and currently ignored.
.It Ic \&ft Op Ar font
Change the font.
The following
.Ar font
arguments are supported:
.Bl -tag -width 4n -offset indent
.It Cm B , BI , 3 , 4
switches to
.Sy bold
font
.It Cm I , 2
switches to
.Em underlined
font
.It Cm R , CW , 1
switches to normal font
.It Cm P No "or no argument"
switches back to the previous font
.El
.Pp
This request takes effect only locally and may be overridden
by macros and escape sequences.
.It Ic \&ftr Ar newname Op Ar oldname
Translate font name.
This is a groff extension and currently ignored.
.It Ic \&fzoom Ar font Op Ar permille
Zoom font size.
Currently ignored.
.It Ic \&gcolor Op Ar colorname
Set glyph color.
This is a groff extension and currently ignored.
.It Ic \&hc Op Ar char
Set the hyphenation character.
Currently ignored.
.It Ic \&hcode Ar char code ...
Set hyphenation codes of characters.
Currently ignored.
.It Ic \&hidechar Ar font char ...
Hide characters in a font.
This is a Heirloom extension and currently ignored.
.It Ic \&hla Ar language
Set hyphenation language.
This is a groff extension and currently ignored.
.It Ic \&hlm Op Ar number
Set maximum number of consecutive hyphenated lines.
Currently ignored.
.It Ic \&hpf Ar filename
Load hyphenation pattern file.
This is a groff extension and currently ignored.
.It Ic \&hpfa Ar filename
Load hyphenation pattern file, appending to the current patterns.
This is a groff extension and currently ignored.
.It Ic \&hpfcode Ar code code ...
Define mapping values for character codes in hyphenation patterns.
This is a groff extension and currently ignored.
.It Ic \&hw Ar word ...
Specify hyphenation points in words.
Currently ignored.
.It Ic \&hy Op Ar mode
Set automatic hyphenation mode.
Currently ignored.
.It Ic \&hylang Ar language
Set hyphenation language.
This is a Heirloom extension and currently ignored.
.It Ic \&hylen Ar nchar
Minimum word length for hyphenation.
This is a Heirloom extension and currently ignored.
.It Ic \&hym Op Ar length
Set hyphenation margin.
This is a groff extension and currently ignored.
.It Ic \&hypp Ar penalty ...
Define hyphenation penalties.
This is a Heirloom extension and currently ignored.
.It Ic \&hys Op Ar length
Set hyphenation space.
This is a groff extension and currently ignored.
.It Ic \&ie Ar condition body
The
.Dq if
half of an if/else conditional.
The result of the conditional is pushed into a stack used by subsequent
invocations of
.Ic \&el ,
which may be separated by any intervening input (or not exist at all).
Its syntax is equivalent to
.Ic \&if .
.It Ic \&if Ar condition body
Begin a conditional.
This request can also be written as follows:
.Bd -unfilled -offset indent
.Pf . Ic \&if Ar condition No \e{ Ns Ar body
.Ar body ... Ns \e}
.Ed
.Bd -unfilled -offset indent
.Pf . Ic \&if Ar condition No \e{\e
.Ar body ...
.Pf . No \e}
.Ed
.Pp
The
.Ar condition
is a boolean expression.
Currently,
.Xr mandoc 1
supports the following subset of roff conditionals:
.Bl -bullet
.It
If
.Sq \&!
is prefixed to
.Ar condition ,
it is logically inverted.
.It
If the first character of
.Ar condition
is
.Sq n
.Pq nroff mode
or
.Sq o
.Pq odd page ,
it evaluates to true.
.It
If the first character of
.Ar condition
is
.Sq c
.Pq character available ,
.Sq e
.Pq even page ,
.Sq t
.Pq troff mode ,
or
.Sq v
.Pq vroff mode ,
it evaluates to false.
.It
If the first character of
.Ar condition
is
.Sq d ,
it evaluates to true if the rest of
.Ar condition
is the name of an existing user defined macro or string;
otherwise, it evaluates to false.
.It
If the first character of
.Ar condition
is
.Sq r ,
it evaluates to true if the rest of
.Ar condition
is the name of an existing number register;
otherwise, it evaluates to false.
.It
If the
.Ar condition
starts with a parenthesis or with an optionally signed
integer number, it is evaluated according to the rules of
.Sx Numerical expressions
explained below.
It evaluates to true if the result is positive,
or to false if the result is zero or negative.
.It
Otherwise, the first character of
.Ar condition
is regarded as a delimiter and it evaluates to true if the string
extending from its first to its second occurrence is equal to the
string extending from its second to its third occurrence.
.It
If
.Ar condition
cannot be parsed, it evaluates to false.
.El
.Pp
If a conditional is false, its children are not processed, but are
syntactically interpreted to preserve the integrity of the input
document.
Thus,
.Pp
.D1 \&.if t .ig
.Pp
will discard the
.Sq \&.ig ,
which may lead to interesting results, but
.Pp
.D1 \&.if t .if t \e{\e
.Pp
will continue to syntactically interpret to the block close of the final
conditional.
Sub-conditionals, in this case, obviously inherit the truth value of
the parent.
.Pp
If the
.Ar body
section is begun by an escaped brace
.Sq \e{ ,
scope continues until the end of the input line containing the
matching closing-brace escape sequence
.Sq \e} .
If the
.Ar body
is not enclosed in braces, scope continues until the end of the line.
If the
.Ar condition
is followed by a
.Ar body
on the same line, whether after a brace or not, then requests and macros
.Em must
begin with a control character.
It is generally more intuitive, in this case, to write
.Bd -unfilled -offset indent
.Pf . Ic \&if Ar condition No \e{\e
.Pf . Ar request
.Pf . No \e}
.Ed
.Pp
than having the request or macro follow as
.Pp
.D1 Pf . Ic \&if Ar condition Pf \e{. Ar request
.Pp
The scope of a conditional is always parsed, but only executed if the
conditional evaluates to true.
.Pp
Note that the
.Sq \e}
is converted into a zero-width escape sequence if not passed as a
standalone macro
.Sq \&.\e} .
For example,
.Pp
.D1 \&.Fl a \e} b
.Pp
will result in
.Sq \e}
being considered an argument of the
.Sq \&Fl
macro.
.It Ic \&ig Op Ar endmacro
Ignore input.
Its syntax can be either
.Bd -literal -offset indent
.Pf . Cm \&ig
.Ar ignored text
\&..
.Ed
.Pp
or
.Bd -literal -offset indent
.Pf . Cm \&ig Ar endmacro
.Ar ignored text
.Pf . Ar endmacro
.Ed
.Pp
In the first case, input is ignored until a
.Sq \&..
request is encountered on its own line.
In the second case, input is ignored until the specified
.Sq Pf . Ar endmacro
is encountered.
Do not use the escape character
.Sq \e
anywhere in the definition of
.Ar endmacro ;
it would cause very strange behaviour.
.Pp
When the
.Ar endmacro
is a roff request or a roff macro, like in
.Pp
.D1 \&.ig if
.Pp
the subsequent invocation of
.Ic \&if
will first terminate the
.Ar ignored text ,
then be invoked as usual.
Otherwise, it only terminates the
.Ar ignored text ,
and arguments following it or the
.Sq \&..
request are discarded.
.It Ic \&in Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width
Change indentation.
See
.Xr man 7 .
Ignored in
.Xr mdoc 7 .
.It Ic \&index Ar register stringname substring
Find a substring in a string.
This is a Heirloom extension and currently unsupported.
.It Ic \&it Ar expression macro
Set an input line trap.
The named
.Ar macro
will be invoked after processing the number of input text lines
specified by the numerical
.Ar expression .
While evaluating the
.Ar expression ,
the unit suffixes described below
.Sx Scaling Widths
are ignored.
.It Ic \&it Ar expression macro
Set an input line trap, not counting lines ending with \ec.
Currently unsupported.
.It Ic \&IX Ar class keystring
To support the generation of a table of contents,
.Xr pod2man 1
emits this user-defined macro, usually without defining it.
To avoid reporting large numbers of spurious errors,
.Xr mandoc 1
ignores it.
.It Ic \&kern Op Cm 1 | 0
Switch kerning on or off.
Currently ignored.
.It Ic \&kernafter Ar font char ... afmunits ...
Increase kerning after some characters.
This is a Heirloom extension and currently ignored.
.It Ic \&kernbefore Ar font char ... afmunits ...
Increase kerning before some characters.
This is a Heirloom extension and currently ignored.
.It Ic \&kernpair Ar font char ... font char ... afmunits
Add a kerning pair to the kerning table.
This is a Heirloom extension and currently ignored.
.It Ic \&lc Op Ar glyph
Define a leader repetition character.
Currently unsupported.
.It Ic \&lc_ctype Ar localename
Set the
.Dv LC_CTYPE
locale.
This is a Heirloom extension and currently unsupported.
.It Ic \&lds Ar macroname string
Define a local string.
This is a Heirloom extension and currently unsupported.
.It Ic \&length Ar register string
Count the number of input characters in a string.
Currently unsupported.
.It Ic \&letadj Ar lspmin lshmin letss lspmax lshmax
Dynamic letter spacing and reshaping.
This is a Heirloom extension and currently ignored.
.It Ic \&lf Ar lineno Op Ar filename
Change the line number for error messages.
Ignored because insecure.
.It Ic \&lg Op Cm 1 | 0
Switch the ligature mechanism on or off.
Currently ignored.
.It Ic \&lhang Ar font char ... afmunits
Hang characters at left margin.
This is a Heirloom extension and currently ignored.
.It Ic \&linetabs Op Cm 1 | 0
Enable or disable line-tabs mode.
This is a groff extension and currently unsupported.
.It Ic \&ll Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width
Change the output line length.
If the
.Ar width
argument is omitted, the line length is reset to its previous value.
The default setting for terminal output is 78n.
If a sign is given, the line length is added to or subtracted from;
otherwise, it is set to the provided value.
Using this request in new manuals is discouraged for several reasons,
among others because it overrides the
.Xr mandoc 1
.Fl O Cm width
command line option.
.It Ic \&lnr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar value Op Ar increment
Set local number register.
This is a Heirloom extension and currently unsupported.
.It Ic \&lnrf Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar value Op Ar increment
Set local floating-point register.
This is a Heirloom extension and currently unsupported.
.It Ic \&lpfx Ar string
Set a line prefix.
This is a Heirloom extension and currently unsupported.
.It Ic \&ls Op Ar factor
Set line spacing.
It takes one integer argument specifying the vertical distance of
subsequent output text lines measured in v units.
Currently ignored.
.It Ic \&lsm Ar macroname
Set a leading spaces trap.
This is a groff extension and currently unsupported.
.It Ic \< Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width
Set title line length.
Currently ignored.
.It Ic \&mc Ar glyph Op Ar dist
Print margin character in the right margin.
The
.Ar dist
is currently ignored; instead, 1n is used.
.It Ic \&mediasize Ar media
Set the device media size.
This is a Heirloom extension and currently ignored.
.It Ic \&minss Ar width
Set minimum word space.
This is a Heirloom extension and currently ignored.
.It Ic \&mk Op Ar register
Mark vertical position.
Currently ignored.
.It Ic \&mso Ar filename
Load a macro file using the search path.
Ignored because insecure.
.It Ic \&na
Disable adjusting without changing the adjustment mode.
Currently ignored.
.It Ic \&ne Op Ar height
Declare the need for the specified minimum vertical space
before the next trap or the bottom of the page.
Currently ignored.
.It Ic \&nf
Switch to no-fill mode.
See
.Xr man 7 .
Ignored by
.Xr mdoc 7 .
.It Ic \&nh
Turn off automatic hyphenation mode.
Currently ignored.
.It Ic \&nhychar Ar char ...
Define hyphenation-inhibiting characters.
This is a Heirloom extension and currently ignored.
.It Ic \&nm Op Ar start Op Ar inc Op Ar space Op Ar indent
Print line numbers.
Currently unsupported.
.It Ic \&nn Op Ar number
Temporarily turn off line numbering.
Currently unsupported.
.It Ic \&nop Ar body
Execute the rest of the input line as a request or macro line.
Currently unsupported.
.It Ic \&nr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression
Define or change a register.
A register is an arbitrary string value that defines some sort of state,
which influences parsing and/or formatting.
For the syntax of
.Ar expression ,
see
.Sx Numerical expressions
below.
If it is prefixed by a sign, the register will be
incremented or decremented instead of assigned to.
.Pp
The following
.Ar register
is handled specially:
.Bl -tag -width Ds
.It Cm nS
If set to a positive integer value, certain
.Xr mdoc 7
macros will behave in the same way as in the
.Em SYNOPSIS
section.
If set to 0, these macros will behave in the same way as outside the
.Em SYNOPSIS
section, even when called within the
.Em SYNOPSIS
section itself.
Note that starting a new
.Xr mdoc 7
section with the
.Ic \&Sh
macro will reset this register.
.El
.It Xo
.Ic \&nrf Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression
.Op Ar increment
.Xc
Define or change a floating-point register.
This is a Heirloom extension and currently unsupported.
.It Ic \&nroff
Force nroff mode.
This is a groff extension and currently ignored.
.It Ic \&ns
Turn on no-space mode.
Currently ignored.
.It Ic \&nx Op Ar filename
Abort processing of the current input file and process another one.
Ignored because insecure.
.It Ic \&open Ar stream file
Open a file for writing.
Ignored because insecure.
.It Ic \&opena Ar stream file
Open a file for appending.
Ignored because insecure.
.It Ic \&os
Output saved vertical space.
Currently ignored.
.It Ic \&output Ar string
Output directly to intermediate output.
Not supported.
.It Ic \&padj Op Cm 1 | 0
Globally control paragraph-at-once adjustment.
This is a Heirloom extension and currently ignored.
.It Ic \&papersize Ar media
Set the paper size.
This is a Heirloom extension and currently ignored.
.It Ic \&pc Op Ar char
Change the page number character.
Currently ignored.
.It Ic \&pev
Print environments.
This is a groff extension and currently ignored.
.It Ic \&pi Ar command
Pipe output to a shell command.
Ignored because insecure.
.It Ic \&PI
Low-level request used by
.Ic \&BP .
This is a Heirloom extension and currently unsupported.
.It Ic \&pl Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height
Change page length.
Currently ignored.
.It Ic \&pm
Print names and sizes of macros, strings, and diversions
to standard error output.
Currently ignored.
.It Ic \&pn Oo Cm + Ns | Ns Cm - Oc Ns Ar number
Change the page number of the next page.
Currently ignored.
.It Ic \&pnr
Print all number registers on standard error output.
Currently ignored.
.It Ic \&po Op Oo Cm + Ns | Ns Cm - Oc Ns Ar offset
Set a horizontal page offset.
If no argument is specified, the page offset is reverted to its
previous value.
If a sign is specified, the new page offset is calculated relative
to the current one; otherwise, it is absolute.
The argument follows the syntax of
.Sx Scaling Widths
and the default scaling unit is
.Cm m .
.It Ic \&ps Op Oo Cm + Ns | Ns Cm - Oc Ns size
Change point size.
Currently ignored.
.It Ic \&psbb Ar filename
Retrieve the bounding box of a PostScript file.
Currently unsupported.
.It Ic \&pshape Ar indent length ...
Set a special shape for the current paragraph.
This is a Heirloom extension and currently unsupported.
.It Ic \&pso Ar command
Include output of a shell command.
Ignored because insecure.
.It Ic \&ptr
Print the names and positions of all traps on standard error output.
This is a groff extension and currently ignored.
.It Ic \&pvs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height
Change post-vertical spacing.
This is a groff extension and currently ignored.
.It Ic \&rchar Ar glyph ...
Remove glyph definitions.
Currently unsupported.
.It Ic \&rd Op Ar prompt Op Ar agument ...
Read from standard input.
Currently ignored.
.It Ic \&recursionlimit Ar maxrec maxtail
Set the maximum stack depth for recursive macros.
This is a Heirloom extension and currently ignored.
.It Ic \&return Op Ar twice
Exit a macro and return to the caller.
Currently unsupported.
.It Ic \&rfschar Ar font glyph ...
Remove font-specific fallback glyph definitions.
Currently unsupported.
.It Ic \&rhang Ar font char ... afmunits
Hang characters at right margin.
This is a Heirloom extension and currently ignored.
.It Ic \&rj Op Ar N
Justify the next
.Ar N
input lines to the right margin without filling.
.Ar N
defaults to 1.
An argument of 0 or less ends right adjustment.
.It Ic \&rm Ar macroname
Remove a request, macro or string.
.It Ic \&rn Ar oldname newname
Rename a request, macro, diversion, or string.
In
.Xr mandoc 1 ,
user-defined macros,
.Xr mdoc 7
and
.Xr man 7
macros, and user-defined strings can be renamed, but renaming of
predefined strings and of
.Nm
requests is not supported, and diversions are not implemented at all.
.It Ic \&rnn Ar oldname newname
Rename a number register.
Currently unsupported.
.It Ic \&rr Ar register
Remove a register.
.It Ic \&rs
End no-space mode.
Currently ignored.
.It Ic \&rt Op Ar dist
Return to marked vertical position.
Currently ignored.
.It Ic \&schar Ar glyph Op Ar string
Define global fallback glyph.
This is a groff extension and currently unsupported.
.It Ic \&sentchar Ar char ...
Define sentence-ending characters.
This is a Heirloom extension and currently ignored.
.It Ic \&shc Op Ar glyph
Change the soft hyphen character.
Currently ignored.
.It Ic \&shift Op Ar number
Shift macro arguments.
Currently unsupported.
.It Ic \&sizes Ar size ...
Define permissible point sizes.
This is a groff extension and currently ignored.
.It Ic \&so Ar filename
Include a source file.
The file is read and its contents processed as input in place of the
.Ic \&so
request line.
To avoid inadvertent inclusion of unrelated files,
.Xr mandoc 1
only accepts relative paths not containing the strings
.Qq ../
and
.Qq /.. .
.Pp
This request requires
.Xr man 1
to change to the right directory before calling
.Xr mandoc 1 ,
per convention to the root of the manual tree.
Typical usage looks like:
.Pp
.Dl \&.so man3/Xcursor.3
.Pp
As the whole concept is rather fragile, the use of
.Ic \&so
is discouraged.
Use
.Xr ln 1
instead.
.It Ic \&sp Op Ar height
Break the output line and emit vertical space.
The argument follows the syntax of
.Sx Scaling Widths
and defaults to one blank line
.Pq Li 1v .
.It Ic \&spacewidth Op Cm 1 | 0
Set the space width from the font metrics file.
This is a Heirloom extension and currently ignored.
.It Ic \&special Op Ar font ...
Define a special font.
This is a groff extension and currently ignored.
.It Ic \&spreadwarn Op Ar width
Warn about wide spacing between words.
Currently ignored.
.It Ic \&ss Ar wordspace Op Ar sentencespace
Set space character size.
Currently ignored.
.It Ic \&sty Ar position style
Associate style with a font position.
This is a groff extension and currently ignored.
.It Ic \&substring Ar stringname startpos Op Ar endpos
Replace a user-defined string with a substring.
Currently unsupported.
.It Ic \&sv Op Ar height
Save vertical space.
Currently ignored.
.It Ic \&sy Ar command
Execute shell command.
Ignored because insecure.
.It Ic \&T&
Re-start a table layout, retaining the options of the prior table
invocation.
See
.Sx \&TS .
.It Ic \&ta Op Ar width ... Op Cm T Ar width ...
Set tab stops.
Each
.Ar width
argument follows the syntax of
.Sx Scaling Widths .
If prefixed by a plus sign, it is relative to the previous tab stop.
The arguments after the
.Cm T
marker are used repeatedly as often as needed; for each reuse,
they are taken relative to the last previously established tab stop.
When
.Ic \&ta
is called without arguments, all tab stops are cleared.
.It Ic \&tc Op Ar glyph
Change tab repetition character.
Currently unsupported.
.It Ic \&TE
End a table context.
See
.Sx \&TS .
.It Ic \&ti Oo Cm + Ns | Ns Cm - Oc Ns Ar width
Break the output line and indent the next output line by
.Ar width .
If a sign is specified, the temporary indentation is calculated
relative to the current indentation; otherwise, it is absolute.
The argument follows the syntax of
.Sx Scaling Widths
and the default scaling unit is
.Cm m .
.It Ic \&tkf Ar font minps width1 maxps width2
Enable track kerning for a font.
Currently ignored.
.It Ic \&tl No \& Ap Ar left Ap Ar center Ap Ar right Ap
Print a title line.
Currently unsupported.
.It Ic \&tm Ar string
Print to standard error output.
Currently ignored.
.It Ic \&tm1 Ar string
Print to standard error output, allowing leading blanks.
This is a groff extension and currently ignored.
.It Ic \&tmc Ar string
Print to standard error output without a trailing newline.
This is a groff extension and currently ignored.
.It Ic \&tr Ar glyph glyph ...
Output character translation.
The first glyph in each pair is replaced by the second one.
Character escapes can be used; for example,
.Pp
.Dl tr \e(xx\e(yy
.Pp
replaces all invocations of \e(xx with \e(yy.
.It Ic \&track Ar font minps width1 maxps width2
Static letter space tracking.
This is a Heirloom extension and currently ignored.
.It Ic \&transchar Ar char ...
Define transparent characters for sentence-ending.
This is a Heirloom extension and currently ignored.
.It Ic \&trf Ar filename
Output the contents of a file, disallowing invalid characters.
This is a groff extension and ignored because insecure.
.It Ic \&trimat Ar left top width height
Set the TrimBox page parameter for PDF generation.
This is a Heirloom extension and currently ignored.
.It Ic \&trin Ar glyph glyph ...
Output character translation, ignored by
.Ic \&asciify .
Currently unsupported.
.It Ic \&trnt Ar glyph glyph ...
Output character translation, ignored by \e!.
Currently unsupported.
.It Ic \&troff
Force troff mode.
This is a groff extension and currently ignored.
.It Ic \&TS
Begin a table, which formats input in aligned rows and columns.
See
.Xr tbl 7
for a description of the tbl language.
.It Ic \&uf Ar font
Globally set the underline font.
Currently ignored.
.It Ic \&ul Op Ar N
Underline next
.Ar N
input lines.
Currently ignored.
.It Ic \&unformat Ar divname
Unformat spaces and tabs in a diversion.
Currently unsupported.
.It Ic \&unwatch Ar macroname
Disable notification for string or macro.
This is a Heirloom extension and currently ignored.
.It Ic \&unwatchn Ar register
Disable notification for register.
This is a Heirloom extension and currently ignored.
.It Ic \&vpt Op Cm 1 | 0
Enable or disable vertical position traps.
This is a groff extension and currently ignored.
.It Ic \&vs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height
Change vertical spacing.
Currently ignored.
.It Ic \&warn Ar flags
Set warning level.
Currently ignored.
.It Ic \&warnscale Ar si
Set the scaling indicator used in warnings.
This is a groff extension and currently ignored.
.It Ic \&watch Ar macroname
Notify on change of string or macro.
This is a Heirloom extension and currently ignored.
.It Ic \&watchlength Ar maxlength
On change, report the contents of macros and strings
up to the specified length.
This is a Heirloom extension and currently ignored.
.It Ic \&watchn Ar register
Notify on change of register.
This is a Heirloom extension and currently ignored.
.It Ic \&wh Ar dist Op Ar macroname
Set a page location trap.
Currently unsupported.
.It Ic \&while Ar condition body
Repeated execution while a condition is true.
Currently unsupported.
.It Ic \&write Oo \(dq Oc Ns Ar string
Write to an open file.
Ignored because insecure.
.It Ic \&writec Oo \(dq Oc Ns Ar string
Write to an open file without appending a newline.
Ignored because insecure.
.It Ic \&writem Ar macroname
Write macro or string to an open file.
Ignored because insecure.
.It Ic \&xflag Ar level
Set the extension level.
This is a Heirloom extension and currently ignored.
.El
.Ss Numerical expressions
The
.Sx \&nr ,
.Sx \&if ,
and
.Sx \&ie
requests accept integer numerical expressions as arguments.
These are always evaluated using the C
.Vt int
type; integer overflow works the same way as in the C language.
Numbers consist of an arbitrary number of digits
.Sq 0
to
.Sq 9
prefixed by an optional sign
.Sq +
or
.Sq - .
Each number may be followed by one optional scaling unit described below
.Sx Scaling Widths .
The following equations hold:
.Bd -literal -offset indent
1i = 6v = 6P = 10m = 10n = 72p = 1000M = 240u = 240
254c = 100i = 24000u = 24000
1f = 65536u = 65536
.Ed
.Pp
The following binary operators are implemented.
Unless otherwise stated, they behave as in the C language:
.Pp
.Bl -tag -width 2n -compact
.It Ic +
addition
.It Ic -
subtraction
.It Ic *
multiplication
.It Ic /
division
.It Ic %
remainder of division
.It Ic <
less than
.It Ic >
greater than
.It Ic ==
equal to
.It Ic =
equal to, same effect as
.Ic ==
(this differs from C)
.It Ic <=
less than or equal to
.It Ic >=
greater than or equal to
.It Ic <>
not equal to (corresponds to C
.Ic != ;
this one is of limited portability, it is supported by Heirloom roff,
but not by groff)
.It Ic &
logical and (corresponds to C
.Ic && )
.It Ic \&:
logical or (corresponds to C
.Ic || )
.It Ic <?
minimum (not available in C)
.It Ic >?
maximum (not available in C)
.El
.Pp
There is no concept of precedence; evaluation proceeds from left to right,
except when subexpressions are enclosed in parentheses.
Inside parentheses, whitespace is ignored.
.Sh ESCAPE SEQUENCE REFERENCE
The
.Xr mandoc 1
.Nm
parser recognises the following escape sequences.
Note that the
.Nm
language defines more escape sequences not implemented in
.Xr mandoc 1 .
In
.Xr mdoc 7
and
.Xr man 7
documents, using escape sequences is discouraged except for those
described in the
.Sx LANGUAGE SYNTAX
section above.
.Pp
A backslash followed by any character not listed here
simply prints that character itself.
.Ss \e<newline>
A backslash at the end of an input line can be used to continue the
logical input line on the next physical input line, joining the text
on both lines together as if it were on a single input line.
.Ss \e<space>
The escape sequence backslash-space
.Pq Sq \e\ \&
is an unpaddable space-sized non-breaking space character; see
.Sx Whitespace .
.Ss \e\(dq
The rest of the input line is treated as
.Sx Comments .
.Ss \e%
Hyphenation allowed at this point of the word; ignored by
.Xr mandoc 1 .
.Ss \e&
Non-printing zero-width character; see
.Sx Whitespace .
.Ss \e\(aq
Acute accent special character; use
.Sq \e(aa
instead.
.Ss \e( Ns Ar cc
.Sx Special Characters
with two-letter names, see
.Xr mandoc_char 7 .
.Ss \e* Ns Bq Ar name
Interpolate the string with the
.Ar name ;
see
.Sx Predefined Strings
and
.Sx ds .
For short names, there are variants
.No \e* Ns Ar c
and
.No \e*( Ns Ar cc .
.Ss \e,
Left italic correction (groff extension); ignored by
.Xr mandoc 1 .
.Ss \e-
Special character
.Dq mathematical minus sign .
.Ss \e/
Right italic correction (groff extension); ignored by
.Xr mandoc 1 .
.Ss \e Ns Bq Ar name
.Sx Special Characters
with names of arbitrary length, see
.Xr mandoc_char 7 .
.Ss \e^
One-twelfth em half-narrow space character, effectively zero-width in
.Xr mandoc 1 .
.Ss \e`
Grave accent special character; use
.Sq \e(ga
instead.
.Ss \e{
Begin conditional input; see
.Sx if .
.Ss \e\(ba
One-sixth em narrow space character, effectively zero-width in
.Xr mandoc 1 .
.Ss \e}
End conditional input; see
.Sx if .
.Ss \e~
Paddable non-breaking space character.
.Ss \e0
Digit width space character.
.Ss \eA\(aq Ns Ar string Ns \(aq
Anchor definition; ignored by
.Xr mandoc 1 .
.Ss \eB\(aq Ns Ar string Ns \(aq
Interpolate
.Sq 1
if
.Ar string
conforms to the syntax of
.Sx Numerical expressions
explained above and
.Sq 0
otherwise.
.Ss \eb\(aq Ns Ar string Ns \(aq
Bracket building function; ignored by
.Xr mandoc 1 .
.Ss \eC\(aq Ns Ar name Ns \(aq
.Sx Special Characters
with names of arbitrary length.
.Ss \ec
When encountered at the end of an input text line,
the next input text line is considered to continue that line,
even if there are request or macro lines in between.
No whitespace is inserted.
.Ss \eD\(aq Ns Ar string Ns \(aq
Draw graphics function; ignored by
.Xr mandoc 1 .
.Ss \ed
Move down by half a line; ignored by
.Xr mandoc 1 .
.Ss \ee
Backslash special character.
.Ss \eF Ns Bq Ar name
Switch font family (groff extension); ignored by
.Xr mandoc 1 .
For short names, there are variants
.No \eF Ns Ar c
and
.No \eF( Ns Ar cc .
.Ss \ef Ns Bq Ar name
Switch to the font
.Ar name ,
see
.Sx Text Decoration .
For short names, there are variants
.No \ef Ns Ar c
and
.No \ef( Ns Ar cc .
.Ss \eg Ns Bq Ar name
Interpolate the format of a number register; ignored by
.Xr mandoc 1 .
For short names, there are variants
.No \eg Ns Ar c
and
.No \eg( Ns Ar cc .
.Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
Set the height of the current font; ignored by
.Xr mandoc 1 .
.Ss \eh\(aq Ns Oo Cm \&| Oc Ns Ar width Ns \(aq
Horizontal motion.
If the vertical bar is given, the motion is relative to the current
indentation.
Otherwise, it is relative to the current position.
The default scaling unit is
.Cm m .
.Ss \ek Ns Bq Ar name
Mark horizontal input place in register; ignored by
.Xr mandoc 1 .
For short names, there are variants
.No \ek Ns Ar c
and
.No \ek( Ns Ar cc .
.Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
Vertical line drawing function; ignored by
.Xr mandoc 1 .
.Ss \el\(aq Ns Ar width Ns Oo Ar c Oc Ns \(aq
Draw a horizontal line of
.Ar width
using the glyph
.Ar c .
.Ss \eM Ns Bq Ar name
Set fill (background) color (groff extension); ignored by
.Xr mandoc 1 .
For short names, there are variants
.No \eM Ns Ar c
and
.No \eM( Ns Ar cc .
.Ss \em Ns Bq Ar name
Set glyph drawing color (groff extension); ignored by
.Xr mandoc 1 .
For short names, there are variants
.No \em Ns Ar c
and
.No \em( Ns Ar cc .
.Ss \eN\(aq Ns Ar number Ns \(aq
Character
.Ar number
on the current font.
.Ss \en Ns Bq Ar name
Interpolate the number register
.Ar name .
For short names, there are variants
.No \en Ns Ar c
and
.No \en( Ns Ar cc .
.Ss \eo\(aq Ns Ar string Ns \(aq
Overstrike, writing all the characters contained in the
.Ar string
to the same output position.
In terminal and HTML output modes,
only the last one of the characters is visible.
.Ss \ep
Break the output line at the end of the current word.
.Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq
Set number register; ignored by
.Xr mandoc 1 .
.Ss \eS\(aq Ns Ar number Ns \(aq
Slant output; ignored by
.Xr mandoc 1 .
.Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
Change point size; ignored by
.Xr mandoc 1 .
Alternative forms
.No \es Ns Oo +|- Oc Ns Ar n ,
.No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq ,
.No \es Ns Bq Oo +|- Oc Ns Ar number ,
and
.No \es Ns Oo +|- Oc Ns Bq Ar number
are also parsed and ignored.
.Ss \et
Horizontal tab; ignored by
.Xr mandoc 1 .
.Ss \eu
Move up by half a line; ignored by
.Xr mandoc 1 .
.Ss \eV Ns Bq Ar name
Interpolate an environment variable; ignored by
.Xr mandoc 1 .
For short names, there are variants
.No \eV Ns Ar c
and
.No \eV( Ns Ar cc .
.Ss \ev\(aq Ns Ar number Ns \(aq
Vertical motion; ignored by
.Xr mandoc 1 .
.Ss \ew\(aq Ns Ar string Ns \(aq
Interpolate the width of the
.Ar string .
The
.Xr mandoc 1
implementation assumes that after expansion of user-defined strings, the
.Ar string
only contains normal characters, no escape sequences, and that each
character has a width of 24 basic units.
.Ss \eX\(aq Ns Ar string Ns \(aq
Output
.Ar string
as device control function; ignored in nroff mode and by
.Xr mandoc 1 .
.Ss \ex\(aq Ns Ar number Ns \(aq
Extra line space function; ignored by
.Xr mandoc 1 .
.Ss \eY Ns Bq Ar name
Output a string as a device control function; ignored in nroff mode and by
.Xr mandoc 1 .
For short names, there are variants
.No \eY Ns Ar c
and
.No \eY( Ns Ar cc .
.Ss \eZ\(aq Ns Ar string Ns \(aq
Print
.Ar string
with zero width and height; ignored by
.Xr mandoc 1 .
.Ss \ez
Output the next character without advancing the cursor position.
.Sh COMPATIBILITY
The
.Xr mandoc 1
implementation of the
.Nm
language is intentionally incomplete.
Unimplemented features include:
.Pp
.Bl -dash -compact
.It
For security reasons,
.Xr mandoc 1
never reads or writes external files except via
.Sx \&so
requests with safe relative paths.
.It
There is no automatic hyphenation, no adjustment to the right margin,
and no centering; the output is always set flush-left.
.It
Support for setting tabulator positions
and tabulator and leader characters is missing,
and support for manually changing indentation is limited.
.It
The
.Sq u
scaling unit is the default terminal unit.
In traditional troff systems, this unit changes depending on the
output media.
.It
Width measurements are implemented in a crude way
and often yield wrong results.
Explicit movement requests and escapes are ignored.
.It
There is no concept of output pages, no support for floats,
graphics drawing, and picture inclusion;
terminal output is always continuous.
.It
Requests regarding color, font families, and glyph manipulation
are ignored.
Font support is very limited.
Kerning is not implemented, and no ligatures are produced.
.It
The
.Qq \(aq
macro control character does not suppress output line breaks.
.It
Diversions are not implemented,
and support for traps is very incomplete.
.It
While recursion is supported,
.Sx \&while
loops are not.
.El
.Pp
The special semantics of the
.Cm nS
number register is an idiosyncracy of
.Ox
manuals and not supported by other
.Xr mdoc 7
implementations.
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr eqn 7 ,
.Xr man 7 ,
.Xr mandoc_char 7 ,
.Xr mdoc 7 ,
.Xr tbl 7
.Rs
.%A Joseph F. Ossanna
.%A Brian W. Kernighan
.%I AT&T Bell Laboratories
.%T Troff User's Manual
.%R Computing Science Technical Report
.%N 54
.%C Murray Hill, New Jersey
.%D 1976 and 1992
.%U http://www.kohala.com/start/troff/cstr54.ps
.Re
.Rs
.%A Joseph F. Ossanna
.%A Brian W. Kernighan
.%A Gunnar Ritter
.%T Heirloom Documentation Tools Nroff/Troff User's Manual
.%D September 17, 2007
.%U http://heirloom.sourceforge.net/doctools/troff.pdf
.Re
.Sh HISTORY
The RUNOFF typesetting system, whose input forms the basis for
.Nm ,
was written in MAD and FAP for the CTSS operating system by Jerome E.
Saltzer in 1964.
Doug McIlroy rewrote it in BCPL in 1969, renaming it
.Nm .
Dennis M. Ritchie rewrote McIlroy's
.Nm
in PDP-11 assembly for
.At v1 ,
Joseph F. Ossanna improved roff and renamed it nroff
for
.At v2 ,
then ported nroff to C as troff, which Brian W. Kernighan released with
.At v7 .
In 1989, James Clarke re-implemented troff in C++, naming it groff.
.Sh AUTHORS
.An -nosplit
This
.Nm
reference was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
and
.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
mandoc-1.14.3/roff.h 0100644 0002007 0000011 00000024767 13141336266 0013603 0 ustar 00schwarze wsrc /* $Id: roff.h,v 1.58 2017/07/08 14:51:05 schwarze Exp $ */
/*
* Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
* Copyright (c) 2013, 2014, 2015, 2017 Ingo Schwarze <schwarze@openbsd.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
struct ohash;
struct mdoc_arg;
union mdoc_data;
enum roff_macroset {
MACROSET_NONE = 0,
MACROSET_MDOC,
MACROSET_MAN
};
enum roff_sec {
SEC_NONE = 0,
SEC_NAME,
SEC_LIBRARY,
SEC_SYNOPSIS,
SEC_DESCRIPTION,
SEC_CONTEXT,
SEC_IMPLEMENTATION, /* IMPLEMENTATION NOTES */
SEC_RETURN_VALUES,
SEC_ENVIRONMENT,
SEC_FILES,
SEC_EXIT_STATUS,
SEC_EXAMPLES,
SEC_DIAGNOSTICS,
SEC_COMPATIBILITY,
SEC_ERRORS,
SEC_SEE_ALSO,
SEC_STANDARDS,
SEC_HISTORY,
SEC_AUTHORS,
SEC_CAVEATS,
SEC_BUGS,
SEC_SECURITY,
SEC_CUSTOM,
SEC__MAX
};
enum roff_type {
ROFFT_ROOT,
ROFFT_BLOCK,
ROFFT_HEAD,
ROFFT_BODY,
ROFFT_TAIL,
ROFFT_ELEM,
ROFFT_TEXT,
ROFFT_TBL,
ROFFT_EQN
};
enum roff_tok {
ROFF_br = 0,
ROFF_ce,
ROFF_ft,
ROFF_ll,
ROFF_mc,
ROFF_po,
ROFF_rj,
ROFF_sp,
ROFF_ta,
ROFF_ti,
ROFF_MAX,
ROFF_ab,
ROFF_ad,
ROFF_af,
ROFF_aln,
ROFF_als,
ROFF_am,
ROFF_am1,
ROFF_ami,
ROFF_ami1,
ROFF_as,
ROFF_as1,
ROFF_asciify,
ROFF_backtrace,
ROFF_bd,
ROFF_bleedat,
ROFF_blm,
ROFF_box,
ROFF_boxa,
ROFF_bp,
ROFF_BP,
ROFF_break,
ROFF_breakchar,
ROFF_brnl,
ROFF_brp,
ROFF_brpnl,
ROFF_c2,
ROFF_cc,
ROFF_cf,
ROFF_cflags,
ROFF_ch,
ROFF_char,
ROFF_chop,
ROFF_class,
ROFF_close,
ROFF_CL,
ROFF_color,
ROFF_composite,
ROFF_continue,
ROFF_cp,
ROFF_cropat,
ROFF_cs,
ROFF_cu,
ROFF_da,
ROFF_dch,
ROFF_Dd,
ROFF_de,
ROFF_de1,
ROFF_defcolor,
ROFF_dei,
ROFF_dei1,
ROFF_device,
ROFF_devicem,
ROFF_di,
ROFF_do,
ROFF_ds,
ROFF_ds1,
ROFF_dwh,
ROFF_dt,
ROFF_ec,
ROFF_ecr,
ROFF_ecs,
ROFF_el,
ROFF_em,
ROFF_EN,
ROFF_eo,
ROFF_EP,
ROFF_EQ,
ROFF_errprint,
ROFF_ev,
ROFF_evc,
ROFF_ex,
ROFF_fallback,
ROFF_fam,
ROFF_fc,
ROFF_fchar,
ROFF_fcolor,
ROFF_fdeferlig,
ROFF_feature,
/* MAN_fi; ignored in mdoc(7) */
ROFF_fkern,
ROFF_fl,
ROFF_flig,
ROFF_fp,
ROFF_fps,
ROFF_fschar,
ROFF_fspacewidth,
ROFF_fspecial,
ROFF_ftr,
ROFF_fzoom,
ROFF_gcolor,
ROFF_hc,
ROFF_hcode,
ROFF_hidechar,
ROFF_hla,
ROFF_hlm,
ROFF_hpf,
ROFF_hpfa,
ROFF_hpfcode,
ROFF_hw,
ROFF_hy,
ROFF_hylang,
ROFF_hylen,
ROFF_hym,
ROFF_hypp,
ROFF_hys,
ROFF_ie,
ROFF_if,
ROFF_ig,
/* MAN_in; ignored in mdoc(7) */
ROFF_index,
ROFF_it,
ROFF_itc,
ROFF_IX,
ROFF_kern,
ROFF_kernafter,
ROFF_kernbefore,
ROFF_kernpair,
ROFF_lc,
ROFF_lc_ctype,
ROFF_lds,
ROFF_length,
ROFF_letadj,
ROFF_lf,
ROFF_lg,
ROFF_lhang,
ROFF_linetabs,
ROFF_lnr,
ROFF_lnrf,
ROFF_lpfx,
ROFF_ls,
ROFF_lsm,
ROFF_lt,
ROFF_mediasize,
ROFF_minss,
ROFF_mk,
ROFF_mso,
ROFF_na,
ROFF_ne,
/* MAN_nf; ignored in mdoc(7) */
ROFF_nh,
ROFF_nhychar,
ROFF_nm,
ROFF_nn,
ROFF_nop,
ROFF_nr,
ROFF_nrf,
ROFF_nroff,
ROFF_ns,
ROFF_nx,
ROFF_open,
ROFF_opena,
ROFF_os,
ROFF_output,
ROFF_padj,
ROFF_papersize,
ROFF_pc,
ROFF_pev,
ROFF_pi,
ROFF_PI,
ROFF_pl,
ROFF_pm,
ROFF_pn,
ROFF_pnr,
ROFF_ps,
ROFF_psbb,
ROFF_pshape,
ROFF_pso,
ROFF_ptr,
ROFF_pvs,
ROFF_rchar,
ROFF_rd,
ROFF_recursionlimit,
ROFF_return,
ROFF_rfschar,
ROFF_rhang,
ROFF_rm,
ROFF_rn,
ROFF_rnn,
ROFF_rr,
ROFF_rs,
ROFF_rt,
ROFF_schar,
ROFF_sentchar,
ROFF_shc,
ROFF_shift,
ROFF_sizes,
ROFF_so,
ROFF_spacewidth,
ROFF_special,
ROFF_spreadwarn,
ROFF_ss,
ROFF_sty,
ROFF_substring,
ROFF_sv,
ROFF_sy,
ROFF_T_,
ROFF_tc,
ROFF_TE,
ROFF_TH,
ROFF_tkf,
ROFF_tl,
ROFF_tm,
ROFF_tm1,
ROFF_tmc,
ROFF_tr,
ROFF_track,
ROFF_transchar,
ROFF_trf,
ROFF_trimat,
ROFF_trin,
ROFF_trnt,
ROFF_troff,
ROFF_TS,
ROFF_uf,
ROFF_ul,
ROFF_unformat,
ROFF_unwatch,
ROFF_unwatchn,
ROFF_vpt,
ROFF_vs,
ROFF_warn,
ROFF_warnscale,
ROFF_watch,
ROFF_watchlength,
ROFF_watchn,
ROFF_wh,
ROFF_while,
ROFF_write,
ROFF_writec,
ROFF_writem,
ROFF_xflag,
ROFF_cblock,
ROFF_RENAMED,
ROFF_USERDEF,
TOKEN_NONE,
MDOC_Dd,
MDOC_Dt,
MDOC_Os,
MDOC_Sh,
MDOC_Ss,
MDOC_Pp,
MDOC_D1,
MDOC_Dl,
MDOC_Bd,
MDOC_Ed,
MDOC_Bl,
MDOC_El,
MDOC_It,
MDOC_Ad,
MDOC_An,
MDOC_Ap,
MDOC_Ar,
MDOC_Cd,
MDOC_Cm,
MDOC_Dv,
MDOC_Er,
MDOC_Ev,
MDOC_Ex,
MDOC_Fa,
MDOC_Fd,
MDOC_Fl,
MDOC_Fn,
MDOC_Ft,
MDOC_Ic,
MDOC_In,
MDOC_Li,
MDOC_Nd,
MDOC_Nm,
MDOC_Op,
MDOC_Ot,
MDOC_Pa,
MDOC_Rv,
MDOC_St,
MDOC_Va,
MDOC_Vt,
MDOC_Xr,
MDOC__A,
MDOC__B,
MDOC__D,
MDOC__I,
MDOC__J,
MDOC__N,
MDOC__O,
MDOC__P,
MDOC__R,
MDOC__T,
MDOC__V,
MDOC_Ac,
MDOC_Ao,
MDOC_Aq,
MDOC_At,
MDOC_Bc,
MDOC_Bf,
MDOC_Bo,
MDOC_Bq,
MDOC_Bsx,
MDOC_Bx,
MDOC_Db,
MDOC_Dc,
MDOC_Do,
MDOC_Dq,
MDOC_Ec,
MDOC_Ef,
MDOC_Em,
MDOC_Eo,
MDOC_Fx,
MDOC_Ms,
MDOC_No,
MDOC_Ns,
MDOC_Nx,
MDOC_Ox,
MDOC_Pc,
MDOC_Pf,
MDOC_Po,
MDOC_Pq,
MDOC_Qc,
MDOC_Ql,
MDOC_Qo,
MDOC_Qq,
MDOC_Re,
MDOC_Rs,
MDOC_Sc,
MDOC_So,
MDOC_Sq,
MDOC_Sm,
MDOC_Sx,
MDOC_Sy,
MDOC_Tn,
MDOC_Ux,
MDOC_Xc,
MDOC_Xo,
MDOC_Fo,
MDOC_Fc,
MDOC_Oo,
MDOC_Oc,
MDOC_Bk,
MDOC_Ek,
MDOC_Bt,
MDOC_Hf,
MDOC_Fr,
MDOC_Ud,
MDOC_Lb,
MDOC_Lp,
MDOC_Lk,
MDOC_Mt,
MDOC_Brq,
MDOC_Bro,
MDOC_Brc,
MDOC__C,
MDOC_Es,
MDOC_En,
MDOC_Dx,
MDOC__Q,
MDOC__U,
MDOC_Ta,
MDOC_MAX,
MAN_TH,
MAN_SH,
MAN_SS,
MAN_TP,
MAN_LP,
MAN_PP,
MAN_P,
MAN_IP,
MAN_HP,
MAN_SM,
MAN_SB,
MAN_BI,
MAN_IB,
MAN_BR,
MAN_RB,
MAN_R,
MAN_B,
MAN_I,
MAN_IR,
MAN_RI,
MAN_nf,
MAN_fi,
MAN_RE,
MAN_RS,
MAN_DT,
MAN_UC,
MAN_PD,
MAN_AT,
MAN_in,
MAN_OP,
MAN_EX,
MAN_EE,
MAN_UR,
MAN_UE,
MAN_MT,
MAN_ME,
MAN_MAX
};
enum roff_next {
ROFF_NEXT_SIBLING = 0,
ROFF_NEXT_CHILD
};
/*
* Indicates that a BODY's formatting has ended, but
* the scope is still open. Used for badly nested blocks.
*/
enum mdoc_endbody {
ENDBODY_NOT = 0,
ENDBODY_SPACE /* Is broken: append a space. */
};
struct roff_node {
struct roff_node *parent; /* Parent AST node. */
struct roff_node *child; /* First child AST node. */
struct roff_node *last; /* Last child AST node. */
struct roff_node *next; /* Sibling AST node. */
struct roff_node *prev; /* Prior sibling AST node. */
struct roff_node *head; /* BLOCK */
struct roff_node *body; /* BLOCK/ENDBODY */
struct roff_node *tail; /* BLOCK */
struct mdoc_arg *args; /* BLOCK/ELEM */
union mdoc_data *norm; /* Normalized arguments. */
char *string; /* TEXT */
const struct tbl_span *span; /* TBL */
struct eqn_box *eqn; /* EQN */
int line; /* Input file line number. */
int pos; /* Input file column number. */
int flags;
#define NODE_VALID (1 << 0) /* Has been validated. */
#define NODE_ENDED (1 << 1) /* Gone past body end mark. */
#define NODE_EOS (1 << 2) /* At sentence boundary. */
#define NODE_LINE (1 << 3) /* First macro/text on line. */
#define NODE_SYNPRETTY (1 << 4) /* SYNOPSIS-style formatting. */
#define NODE_BROKEN (1 << 5) /* Must validate parent when ending. */
#define NODE_DELIMO (1 << 6)
#define NODE_DELIMC (1 << 7)
#define NODE_NOSRC (1 << 8) /* Generated node, not in input file. */
#define NODE_NOPRT (1 << 9) /* Shall not print anything. */
int prev_font; /* Before entering this node. */
int aux; /* Decoded node data, type-dependent. */
enum roff_tok tok; /* Request or macro ID. */
enum roff_type type; /* AST node type. */
enum roff_sec sec; /* Current named section. */
enum mdoc_endbody end; /* BODY */
};
struct roff_meta {
char *msec; /* Manual section, usually a digit. */
char *vol; /* Manual volume title. */
char *os; /* Operating system. */
char *arch; /* Machine architecture. */
char *title; /* Manual title, usually CAPS. */
char *name; /* Leading manual name. */
char *date; /* Normalized date. */
int hasbody; /* Document is not empty. */
int rcsids; /* Bits indexed by enum mandoc_os. */
enum mandoc_os os_e; /* Operating system. */
};
struct roff_man {
struct roff_meta meta; /* Document meta-data. */
struct mparse *parse; /* Parse pointer. */
struct roff *roff; /* Roff parser state data. */
struct ohash *mdocmac; /* Mdoc macro lookup table. */
struct ohash *manmac; /* Man macro lookup table. */
const char *os_s; /* Default operating system. */
struct roff_node *first; /* The first node parsed. */
struct roff_node *last; /* The last node parsed. */
struct roff_node *last_es; /* The most recent Es node. */
int quick; /* Abort parse early. */
int flags; /* Parse flags. */
#define MDOC_LITERAL (1 << 1) /* In a literal scope. */
#define MDOC_PBODY (1 << 2) /* In the document body. */
#define MDOC_NEWLINE (1 << 3) /* First macro/text in a line. */
#define MDOC_PHRASE (1 << 4) /* In a Bl -column phrase. */
#define MDOC_PHRASELIT (1 << 5) /* Literal within a phrase. */
#define MDOC_FREECOL (1 << 6) /* `It' invocation should close. */
#define MDOC_SYNOPSIS (1 << 7) /* SYNOPSIS-style formatting. */
#define MDOC_KEEP (1 << 8) /* In a word keep. */
#define MDOC_SMOFF (1 << 9) /* Spacing is off. */
#define MDOC_NODELIMC (1 << 10) /* Disable closing delimiter handling. */
#define MAN_ELINE (1 << 11) /* Next-line element scope. */
#define MAN_BLINE (1 << 12) /* Next-line block scope. */
#define MDOC_PHRASEQF (1 << 13) /* Quote first word encountered. */
#define MDOC_PHRASEQL (1 << 14) /* Quote last word of this phrase. */
#define MDOC_PHRASEQN (1 << 15) /* Quote first word of the next phrase. */
#define MAN_LITERAL MDOC_LITERAL
#define MAN_NEWLINE MDOC_NEWLINE
enum roff_macroset macroset; /* Kind of high-level macros used. */
enum roff_sec lastsec; /* Last section seen. */
enum roff_sec lastnamed; /* Last standard section seen. */
enum roff_next next; /* Where to put the next node. */
};
extern const char *const *roff_name;
void deroff(char **, const struct roff_node *);
struct ohash *roffhash_alloc(enum roff_tok, enum roff_tok);
enum roff_tok roffhash_find(struct ohash *, const char *, size_t);
void roffhash_free(struct ohash *);
void roff_validate(struct roff_man *);
mandoc-1.14.3/roff_int.h 0100644 0002007 0000011 00000003607 13141336266 0014443 0 ustar 00schwarze wsrc /* $Id: roff_int.h,v 1.9 2017/07/08 17:52:50 schwarze Exp $ */
/*
* Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
* Copyright (c) 2013, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
struct roff_node *roff_node_alloc(struct roff_man *, int, int,
enum roff_type, int);
void roff_node_append(struct roff_man *, struct roff_node *);
void roff_word_alloc(struct roff_man *, int, int, const char *);
void roff_word_append(struct roff_man *, const char *);
void roff_elem_alloc(struct roff_man *, int, int, int);
struct roff_node *roff_block_alloc(struct roff_man *, int, int, int);
struct roff_node *roff_head_alloc(struct roff_man *, int, int, int);
struct roff_node *roff_body_alloc(struct roff_man *, int, int, int);
void roff_node_unlink(struct roff_man *, struct roff_node *);
void roff_node_free(struct roff_node *);
void roff_node_delete(struct roff_man *, struct roff_node *);
/*
* Functions called from roff.c need to be declared here,
* not in libmdoc.h or libman.h, even if they are specific
* to either the mdoc(7) or the man(7) parser.
*/
void man_breakscope(struct roff_man *, int);
void mdoc_argv_free(struct mdoc_arg *);
mandoc-1.14.3/soelim.1 0100644 0002007 0000011 00000005145 13141336266 0014035 0 ustar 00schwarze wsrc .\" $Id: soelim.1,v 1.5 2017/07/04 23:40:01 schwarze Exp $
.\"
.\" Copyright (c) 2014 Baptiste Daroussin <bapt@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd $Mdocdate: July 4 2017 $
.Dt SOELIM 1
.Os
.Sh NAME
.Nm soelim
.Nd interpret .so requests in manpages
.Sh SYNOPSIS
.Nm
.Op Fl Crtv
.Op Fl I Ar dir
.Op Ar files ...
.Sh DESCRIPTION
.Nm
reads
.Ar files
lines by lines.
.Pp
If a line starts by:
.Dq .so anotherfile
it replace the line by processing
.Dq anotherfile .
Otherwise the line is printed to stdout.
.Bl -tag -width "-I dir"
.It Fl C
Recognise
.Em .so
when not followed by a space character.
.It Fl r
Compatibility with GNU groff's
.Nm soelim
(does nothing).
.It Fl t
Compatibility with GNU groff's
.Nm soelim
(does nothing).
.It Fl v
Compatibility with GNU groff's
.Nm soelim
(does nothing).
.It Fl I Ar dir
This option specify directories where
.Nm
searches for files (both those on the command line and those named in
.Dq .so
directive.)
This options may be specified multiple times.
The directories will be searched in the order specified.
.El
.Pp
The files are always searched first in the current directory.
.Pp
A file specified with an absolute path will be opened directly without
performing a search.
.Sh SEE ALSO
.Xr mandoc 1
.Sh AUTHORS
This version of the
.Nm
utility was written by
.An Baptiste Daroussin Aq Mt bapt@freebsd.org .
mandoc-1.14.3/st.in 0100644 0002007 0000011 00000010566 13141336266 0013444 0 ustar 00schwarze wsrc /* $Id: st.in,v 1.29 2017/06/24 13:49:29 schwarze Exp $ */
/*
* Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
/*
* This file defines the .St macro arguments. If you add a new
* standard, make sure that the left-and side corresponds to the .St
* argument (like .St -p1003.1) and the right-hand side corresponds to
* the formatted output string.
*
* Be sure to escape strings.
* The non-breaking blanks prevent ending an output line right before
* a number. Groff prevent line breaks at the same places.
*
* REMEMBER TO ADD NEW STANDARDS TO MDOC.7!
*/
LINE("-p1003.1-88", "IEEE Std 1003.1-1988 (\\(LqPOSIX.1\\(Rq)")
LINE("-p1003.1-90", "IEEE Std 1003.1-1990 (\\(LqPOSIX.1\\(Rq)")
LINE("-p1003.1-96", "ISO/IEC 9945-1:1996 (\\(LqPOSIX.1\\(Rq)")
LINE("-p1003.1-2001", "IEEE Std 1003.1-2001 (\\(LqPOSIX.1\\(Rq)")
LINE("-p1003.1-2004", "IEEE Std 1003.1-2004 (\\(LqPOSIX.1\\(Rq)")
LINE("-p1003.1-2008", "IEEE Std 1003.1-2008 (\\(LqPOSIX.1\\(Rq)")
LINE("-p1003.1", "IEEE Std 1003.1 (\\(LqPOSIX.1\\(Rq)")
LINE("-p1003.1b", "IEEE Std 1003.1b (\\(LqPOSIX.1b\\(Rq)")
LINE("-p1003.1b-93", "IEEE Std 1003.1b-1993 (\\(LqPOSIX.1b\\(Rq)")
LINE("-p1003.1c-95", "IEEE Std 1003.1c-1995 (\\(LqPOSIX.1c\\(Rq)")
LINE("-p1003.1g-2000", "IEEE Std 1003.1g-2000 (\\(LqPOSIX.1g\\(Rq)")
LINE("-p1003.1i-95", "IEEE Std 1003.1i-1995 (\\(LqPOSIX.1i\\(Rq)")
LINE("-p1003.2", "IEEE Std 1003.2 (\\(LqPOSIX.2\\(Rq)")
LINE("-p1003.2-92", "IEEE Std 1003.2-1992 (\\(LqPOSIX.2\\(Rq)")
LINE("-p1003.2a-92", "IEEE Std 1003.2a-1992 (\\(LqPOSIX.2\\(Rq)")
LINE("-isoC", "ISO/IEC 9899:1990 (\\(LqISO\\~C90\\(Rq)")
LINE("-isoC-90", "ISO/IEC 9899:1990 (\\(LqISO\\~C90\\(Rq)")
LINE("-isoC-amd1", "ISO/IEC 9899/AMD1:1995 (\\(LqISO\\~C90, Amendment 1\\(Rq)")
LINE("-isoC-tcor1", "ISO/IEC 9899/TCOR1:1994 (\\(LqISO\\~C90, Technical Corrigendum 1\\(Rq)")
LINE("-isoC-tcor2", "ISO/IEC 9899/TCOR2:1995 (\\(LqISO\\~C90, Technical Corrigendum 2\\(Rq)")
LINE("-isoC-99", "ISO/IEC 9899:1999 (\\(LqISO\\~C99\\(Rq)")
LINE("-isoC-2011", "ISO/IEC 9899:2011 (\\(LqISO\\~C11\\(Rq)")
LINE("-iso9945-1-90", "ISO/IEC 9945-1:1990 (\\(LqPOSIX.1\\(Rq)")
LINE("-iso9945-1-96", "ISO/IEC 9945-1:1996 (\\(LqPOSIX.1\\(Rq)")
LINE("-iso9945-2-93", "ISO/IEC 9945-2:1993 (\\(LqPOSIX.2\\(Rq)")
LINE("-ansiC", "ANSI X3.159-1989 (\\(LqANSI\\~C89\\(Rq)")
LINE("-ansiC-89", "ANSI X3.159-1989 (\\(LqANSI\\~C89\\(Rq)")
LINE("-ieee754", "IEEE Std 754-1985")
LINE("-iso8802-3", "ISO 8802-3: 1989")
LINE("-iso8601", "ISO 8601")
LINE("-ieee1275-94", "IEEE Std 1275-1994 (\\(LqOpen Firmware\\(Rq)")
LINE("-xpg3", "X/Open Portability Guide Issue\\~3 (\\(LqXPG3\\(Rq)")
LINE("-xpg4", "X/Open Portability Guide Issue\\~4 (\\(LqXPG4\\(Rq)")
LINE("-xpg4.2", "X/Open Portability Guide Issue\\~4, Version\\~2 (\\(LqXPG4.2\\(Rq)")
LINE("-xbd5", "X/Open Base Definitions Issue\\~5 (\\(LqXBD5\\(Rq)")
LINE("-xcu5", "X/Open Commands and Utilities Issue\\~5 (\\(LqXCU5\\(Rq)")
LINE("-xsh4.2", "X/Open System Interfaces and Headers Issue\\~4, Version\\~2 (\\(LqXSH4.2\\(Rq)")
LINE("-xsh5", "X/Open System Interfaces and Headers Issue\\~5 (\\(LqXSH5\\(Rq)")
LINE("-xns5", "X/Open Networking Services Issue\\~5 (\\(LqXNS5\\(Rq)")
LINE("-xns5.2", "X/Open Networking Services Issue\\~5.2 (\\(LqXNS5.2\\(Rq)")
LINE("-xcurses4.2", "X/Open Curses Issue\\~4, Version\\~2 (\\(LqXCURSES4.2\\(Rq)")
LINE("-susv1", "Version\\~1 of the Single UNIX Specification (\\(LqSUSv1\\(Rq)")
LINE("-susv2", "Version\\~2 of the Single UNIX Specification (\\(LqSUSv2\\(Rq)")
LINE("-susv3", "Version\\~3 of the Single UNIX Specification (\\(LqSUSv3\\(Rq)")
LINE("-susv4", "Version\\~4 of the Single UNIX Specification (\\(LqSUSv4\\(Rq)")
LINE("-svid4", "System\\~V Interface Definition, Fourth Edition (\\(LqSVID4\\(Rq)")
mandoc-1.14.3/tag.h 0100644 0002007 0000011 00000002112 13141336266 0013376 0 ustar 00schwarze wsrc /* $Id: tag.h,v 1.7 2015/11/20 21:59:54 schwarze Exp $ */
/*
* Copyright (c) 2015 Ingo Schwarze <schwarze@openbsd.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
struct tag_files {
char ofn[20];
char tfn[20];
int ofd;
int tfd;
pid_t tcpgid;
pid_t pager_pid;
};
struct tag_files *tag_init(void);
void tag_put(const char *, int, size_t);
void tag_write(void);
void tag_unlink(void);
mandoc-1.14.3/tbl.3 0100644 0002007 0000011 00000015703 13141336266 0013331 0 ustar 00schwarze wsrc .\" $Id: tbl.3,v 1.2 2015/01/30 04:11:50 schwarze Exp $
.\"
.\" Copyright (c) 2013 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: January 30 2015 $
.Dt TBL 3
.Os
.Sh NAME
.Nm tbl_alloc ,
.Nm tbl_read ,
.Nm tbl_restart ,
.Nm tbl_span ,
.Nm tbl_end ,
.Nm tbl_free
.Nd roff table parser library for mandoc
.Sh SYNOPSIS
.In mandoc.h
.In libmandoc.h
.In libroff.h
.Ft struct tbl_node *
.Fo tbl_alloc
.Fa "int pos"
.Fa "int line"
.Fa "struct mparse *parse"
.Fc
.Ft enum rofferr
.Fo tbl_read
.Fa "struct tbl_node *tbl"
.Fa "int ln"
.Fa "const char *p"
.Fa "int offs"
.Fc
.Ft void
.Fo tbl_restart
.Fa "int line"
.Fa "int pos"
.Fa "struct tbl_node *tbl"
.Fc
.Ft const struct tbl_span *
.Fo tbl_span
.Fa "struct tbl_node *tbl"
.Fc
.Ft void
.Fo tbl_end
.Fa "struct tbl_node **tblp"
.Fc
.Ft void
.Fo tbl_free
.Fa "struct tbl_node *tbl"
.Fc
.Sh DESCRIPTION
This library is tightly integrated into the
.Xr mandoc 1
utility and not designed for stand-alone use.
The present manual is intended as a reference for developers working on
.Xr mandoc 1 .
.Ss Data structures
Unless otherwise noted, all of the following data structures are defined in
.In mandoc.h
and are deleted in
.Fn tbl_free .
.Bl -tag -width Ds
.It Vt struct tbl_node
This structure describes a complete table.
It is defined in
.In libroff.h ,
created in
.Fn tbl_alloc ,
and stored in the members
.Fa first_tbl ,
.Fa last_tbl ,
and
.Fa tbl
of
.Vt struct roff Bq Pa roff.c .
.Pp
The
.Fa first_span ,
.Fa current_span ,
.Fa last_span ,
and
.Fa next
members may be
.Dv NULL .
The
.Fa first_row
and
.Fa last_row
members may be
.Dv NULL ,
but if there is a span, the function
.Fn tbl_layout
guarantees that these pointers are not
.Dv NULL .
The function
.Fn tbl_alloc
guarantees that the
.Fa parse
member is not
.Dv NULL .
.It Vt struct tbl_opts
This structure describes the options of one table.
It is used as a substructure of
.Vt struct tbl_node
and thus created and deleted together with it.
It is filled in
.Fn tbl_options .
.It Vt struct tbl_row
This structure describes one layout line in a table
by maintaining a list of all the cells in that line.
It is allocated and filled in
.Fn row Bq Pa tbl_layout.c
and referenced from the
.Fa layout
member of
.Vt struct tbl_node .
.Pp
The
.Fa next
member may be
.Dv NULL .
The function
.Fn tbl_layout
guarantees that the
.Fa first
and
.Fa last
members are not NULL.
.It Vt struct tbl_cell
This structure describes one layout cell in a table,
in particular its alignment, membership in spans, and
usage for lines.
It is allocated and filled in
.Fn cell_alloc Bq Pa tbl_layout.c
and referenced from the
.Fa first
and
.Fa last
members of
.Vt struct tbl_row .
.Pp
The
.Fa next
member may be
.Dv NULL .
.It Vt struct tbl_span
This structure describes one data line in a table
by maintaining a list of all data cells in that line
or by specifying that it is a horizontal line.
It is allocated and filled in
.Fn newspan Bq Pa tbl_data.c
which is called from
.Fn tbl_data
and referenced from the
.Fa first_span ,
.Fa current_span ,
and
.Fa last_span
members of
.Vt struct tbl_node ,
and from the
.Fa span
members of
.Vt struct man_node
and
.Vt struct mdoc_node
from
.In man.h
and
.In mdoc.h .
.Pp
The
.Fa first ,
.Fa last ,
.Fa prev ,
and
.Fa next
members may be
.Dv NULL .
The function
.Fn newspan Bq Pa tbl_data.c
guarantees that the
.Fa opts
and
.Fa layout
members are not
.Dv NULL .
.It Vt struct tbl_dat
This structure describes one data cell in a table by specifying
whether it contains a line or data, whether it spans additional
layout cells, and by storing the data.
It is allocated and filled in
.Fn tbl_data
and referenced from the
.Fa first
and
.Fa last
members of
.Vt struct tbl_span .
.Pp
The
.Fa string
and
.Fa next
members may be
.Dv NULL .
The function
.Fn getdata
guarantees that the
.Fa layout
member is not
.Dv NULL .
.El
.Ss Interface functions
The following functions are implemented in
.Pa tbl.c ,
and all callers in
.Pa roff.c .
.Bl -tag -width Ds
.It Fn tbl_alloc
Allocates, initializes, and returns a new
.Vt struct tbl_node .
Called from
.Fn roff_TS .
.It Fn tbl_read
Dispatches to
.Fn tbl_option ,
.Fn tbl_layout ,
.Fn tbl_cdata ,
and
.Fn tbl_data ,
see below.
Called from
.Fn roff_parseln .
.It Fn tbl_restart
Resets the
.Fa part
member of
.Vt struct tbl_node
to
.Dv TBL_PART_LAYOUT .
Called from
.Fn roff_T_ .
.It Fn tbl_span
On the first call, return the first
.Vt struct tbl_span ;
for later calls, return the next one or
.Dv NULL .
Called from
.Fn roff_span .
.It Fn tbl_end
Flags the last span as
.Dv TBL_SPAN_LAST
and clears the pointer passed as an argment.
Called from
.Fn roff_TE
and
.Fn roff_endparse .
.It Fn tbl_free
Frees the specified
.Vt struct tbl_node
and all the tbl_row, tbl_cell, tbl_span, and tbl_dat structures
referenced from it.
Called from
.Fn roff_free
and
.Fn roff_reset .
.El
.Ss Private functions
.Bl -tag -width Ds
.It Ft int Fn tbl_options "struct tbl_node *tbl" "int ln" "const char *p"
Parses the options line into
.Vt struct tbl_opts .
Implemented in
.Pa tbl_opts.c ,
called from
.Fn tbl_read .
.It Ft int Fn tbl_layout "struct tbl_node *tbl" "int ln" "const char *p"
Allocates and fills one
.Vt struct tbl_row
for each layout line and one
.Vt struct tbl_cell
for each layout cell.
Implemented in
.Pa tbl_layout.c ,
called from
.Fn tbl_read .
.It Ft int Fn tbl_data "struct tbl_node *tbl" "int ln" "const char *p"
Allocates one
.Vt struct tbl_span
for each data line and calls
.Fn getdata
for each data cell.
Implemented in
.Pa tbl_data.c ,
called from
.Fn tbl_read .
.It Ft int Fn tbl_cdata "struct tbl_node *tbl" "int ln" "const char *p"
Continues parsing a data line:
When finding
.Sq T} ,
switches back to
.Dv TBL_PART_DATA
mode and calls
.Fn getdata
if there are more data cells on the line.
Otherwise, appends the data to the current data cell.
Implemented in
.Pa tbl_data.c ,
called from
.Fn tbl_read .
.It Xo
.Ft int
.Fo getdata
.Fa "struct tbl_node *tbl"
.Fa "struct tbl_span *dp"
.Fa "int ln"
.Fa "const char *p"
.Fa "int *pos"
.Fc
.Xc
Parses one data cell into one
.Vt struct tbl_dat .
Implemented in
.Pa tbl_data.c ,
called from
.Fn tbl_data
and
.Fn tbl_cdata .
.El
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr mandoc 3 ,
.Xr tbl 7
.Sh AUTHORS
.An -nosplit
The
.Nm tbl
library was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
with contributions from
.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
mandoc-1.14.3/tbl.7 0100644 0002007 0000011 00000024222 13141336266 0013331 0 ustar 00schwarze wsrc .\" $Id: tbl.7,v 1.28 2017/06/28 00:59:57 schwarze Exp $
.\"
.\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2014, 2015, 2017 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: June 28 2017 $
.Dt TBL 7
.Os
.Sh NAME
.Nm tbl
.Nd tbl language reference for mandoc
.Sh DESCRIPTION
The
.Nm tbl
language formats tables.
It is used within
.Xr mdoc 7
and
.Xr man 7
pages.
This manual describes the subset of the
.Nm
language accepted by the
.Xr mandoc 1
utility.
.Pp
Each table is started with a
.Xr roff 7
.Ic \&TS
macro, consist of at most one line of
.Sx Options ,
one or more
.Sx Layout
lines, one or more
.Sx Data
lines, and ends with a
.Ic \&TE
macro.
All input must be 7-bit ASCII.
.Ss Options
If the first input line of a table ends with a semicolon, it contains
case-insensitive options separated by spaces, tabs, or commas.
Otherwise, it is interpreted as the first
.Sx Layout
line.
.Pp
The following options are available.
Some of them require arguments enclosed in parentheses:
.Bl -tag -width Ds
.It Cm allbox
Draw a single-line box around each table cell.
.It Cm box
Draw a single-line box around the table.
For GNU compatibility, this may also be invoked with
.Cm frame .
.It Cm center
Center the table instead of left-adjusting it.
For GNU compatibility, this may also be invoked with
.Cm centre .
.It Cm decimalpoint
Use the single-character argument as the decimal point with the
.Cm n
layout key.
This is a GNU extension.
.It Cm delim
Use the two characters of the argument as
.Xr eqn 7
delimiters.
Currently unsupported.
.It Cm doublebox
Draw a double-line box around the table.
For GNU compatibility, this may also be invoked with
.Cm doubleframe .
.It Cm expand
Increase the width of the table to the current line length.
Currently ignored.
.It Cm linesize
Draw lines with the point size given by the unsigned integer argument.
Currently ignored.
.It Cm nokeep
Allow page breaks within the table.
This is a GNU extension and currently ignored.
.It Cm nospaces
Ignore leading and trailing spaces in data cells.
This is a GNU extension and currently ignored.
.It Cm nowarn
Suppress warnings about tables exceeding the current line length.
This is a GNU extension and currently ignored.
.It Cm tab
Use the single-character argument as a delimiter between data cells.
By default, the horizontal tabulator character is used.
.El
.Ss Layout
The table layout follows an
.Sx Options
line or a
.Xr roff 7
.Ic \&TS
or
.Ic \&T&
macro.
Each layout line specifies how one line of
.Sx Data
is formatted.
The last layout line ends with a full stop.
It also applies to all remaining data lines.
Multiple layout lines can be joined by commas on a single physical
input line.
.Pp
Each layout line consists of one or more layout cell specifications,
optionally separated by whitespace.
The following case-insensitive key characters start a new cell
specification:
.Bl -tag -width 2n
.It Cm c
Center the string in this cell.
.It Cm r
Right-justify the string in this cell.
.It Cm l
Left-justify the string in this cell.
.It Cm n
Justify a number around its last decimal point.
If no decimal point is found in the number,
it is assumed to trail the number.
.It Cm s
Horizontally span columns from the last
.Pf non- Cm s
layout cell.
It is an error if a column span follows a
.Cm _
or
.Cm =
cell, or comes first on a layout line.
The combined cell as a whole consumes only one cell
of the corresponding data line.
.It Cm a
Left-justify a string and pad with one space.
.It Cm ^
Vertically span rows from the last
.Pf non- Cm ^
layout cell.
It is an error to invoke a vertical span on the first layout line.
Unlike a horizontal span, a vertical span consumes a data cell
and discards the content.
.It Cm _
Draw a single horizontal line in this cell.
This consumes a data cell and discards the content.
It may also be invoked with
.Cm \- .
.It Cm =
Draw a double horizontal line in this cell.
This consumes a data cell and discards the content.
.El
.Pp
Each cell key may be followed by zero or more of the following
case-insensitive modifiers:
.Bl -tag -width 2n
.It Cm b
Use a bold font for the contents of this cell.
.It Cm d
Move content down to the last row of this vertical span.
Currently ignored.
.It Cm e
Make this column wider to match the maximum width
of any other column also having the
.Cm e
modifier.
.It Cm f
The next character selects the font to use for this cell.
See the
.Xr roff 7
manual for supported one-character font names.
.It Cm i
Use an italic font for the contents of this cell.
.It Cm m
Specify a cell start macro.
This is a GNU extension and currently unsupported.
.It Cm p
Set the point size to the following unsigned argument,
or change it by the following signed argument.
Currently ignored.
.It Cm v
Set the vertical line spacing to the following unsigned argument,
or change it by the following signed argument.
Currently ignored.
.It Cm t
Do not vertically center content in this vertical span,
leave it in the top row.
Currently ignored.
.It Cm u
Move cell content up by half a table row.
Currently ignored.
.It Cm w
Specify a minimum column width.
.It Cm x
After determining the width of all other columns, distribute the
rest of the line length among all columns having the
.Cm x
modifier.
.It Cm z
Do not use this cell for determining the width of this column.
.It Cm \&|
Draw a single vertical line to the right of this cell.
.It Cm ||
Draw a double vertical line to the right of this cell.
.El
.Pp
If a modifier consists of decimal digits,
it specifies a minimum spacing in units of
.Cm n
between this column and the next column to the right.
The default is 3.
If there is a vertical line, it is drawn inside the spacing.
.Ss Data
The data section follows the last
.Sx Layout
line.
Each data line consists of one or more data cells, delimited by
.Cm tab
characters.
.Pp
If a data cells contains only the single character
.Ql _
or
.Ql = ,
a single or double horizontal line is drawn across the cell,
joining its neighbours.
If a data cells contains only the two character sequence
.Ql \e_
or
.Ql \e= ,
a single or double horizontal line is drawn inside the cell,
not joining its neighbours.
If a data line contains nothing but the single character
.Ql _
or
.Ql = ,
a horizontal line across the whole table is inserted
without consuming a layout row.
.Pp
In place of any data cell, a text block can be used.
It starts with
.Ic \&T{
at the end of a physical input line.
Input line breaks inside the text block
neither end the text block nor its data cell.
It only ends if
.Ic \&T}
occurs at the beginning of a physical input line and is followed
by an end-of-cell indicator.
If the
.Ic \&T}
is followed by the end of the physical input line, the text block,
the data cell, and the data line ends at this point.
If the
.Ic \&T}
is followed by the
.Cm tab
character, only the text block and the data cell end,
but the data line continues with the data cell following the
.Cm tab
character.
If
.Ic \&T}
is followed by any other character, it does not end the text block,
which instead continues to the following physical input line.
.Sh EXAMPLES
String justification and font selection:
.Bd -literal -offset indent
\&.TS
rb c lb
r ci l.
r center l
ri ce le
right c left
\&.TE
.Ed
.Bd -filled -offset indent
.TS
rb c lb
r ci l.
r center l
ri ce le
right c left
.TE
.Ed
.Pp
Some ports in
.Ox 6.1
to show number alignment and line drawing:
.Bd -literal -offset indent
\&.TS
box tab(:);
r| l
r n.
software:version
_
AFL:2.39b
Mutt:1.8.0
Ruby:1.8.7.374
TeX Live:2015
\&.TE
.Ed
.Bd -filled -offset indent
.TS
box tab(:);
r| l
r n.
software:version
_
AFL:2.39b
Mutt:1.8.0
Ruby:1.8.7.374
TeX Live:2015
.TE
.Ed
.sp 2v
Spans and skipping width calculations:
.Bd -literal -offset indent
\&.TS
box tab(:);
lz s | rt
lt| cb| ^
^ | rz s.
left:r
l:center:
:right
\&.TE
.Ed
.Bd -filled -offset indent
.TS
box tab(:);
lz s | rt
lt| cb| ^
^ | rz s.
left:r
l:center:
:right
.TE
.Ed
.sp 2v
Text blocks, specifying spacings and specifying and equalizing
column widths, putting lines into individual cells, and overriding
.Cm allbox :
.Bd -literal -offset indent
\&.TS
allbox tab(:);
le le||7 lw10.
The fourth line:_:line 1
of this column:=:line 2
determines:\_:line 3
the column width.:T{
This text is too wide to fit into a column of width 17.
T}:line 4
T{
No break here.
T}::line 5
\&.TE
.Ed
.Bd -filled -offset indent
.TS
allbox tab(:);
le le||7 lw10.
The fourth line:_:line 1
of this column:=:line 2
determines:\_:line 3
the column width.:T{
This text is too wide to fit into a column of width 17.
T}:line 4
T{
No break here.
T}::line 5
.TE
.Ed
.sp 2v
These examples were constructed to demonstrate many
.Nm
features in a compact way.
In real manual pages, keep tables as simple as possible:
Like that, they usually look better, are less fragile, and more portable.
.Sh COMPATIBILITY
The
.Xr mandoc 1
implementation of
.Nm
doesn't support
.Xr mdoc 7
and
.Xr man 7
macros and
.Xr eqn 7
equations inside tables.
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr man 7 ,
.Xr mandoc_char 7 ,
.Xr mdoc 7 ,
.Xr roff 7
.Rs
.%A M. E. Lesk
.%T Tbl\(emA Program to Format Tables
.%D June 11, 1976
.Re
.Sh HISTORY
The tbl utility, a preprocessor for troff, was originally written by M.
E. Lesk at Bell Labs in 1975.
The GNU reimplementation of tbl, part of the groff package, was released
in 1990 by James Clark.
A standalone tbl implementation was written by Kristaps Dzonsons in
2010.
This formed the basis of the implementation that is part of the
.Xr mandoc 1
utility.
.Sh AUTHORS
This
.Nm
reference was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
and
.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
mandoc-1.14.3/term.h 0100644 0002007 0000011 00000014011 13141336266 0013573 0 ustar 00schwarze wsrc /* $Id: term.h,v 1.130 2017/07/08 14:51:05 schwarze Exp $ */
/*
* Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
* Copyright (c) 2011-2015, 2017 Ingo Schwarze <schwarze@openbsd.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
enum termenc {
TERMENC_ASCII,
TERMENC_LOCALE,
TERMENC_UTF8
};
enum termtype {
TERMTYPE_CHAR,
TERMTYPE_PS,
TERMTYPE_PDF
};
enum termfont {
TERMFONT_NONE = 0,
TERMFONT_BOLD,
TERMFONT_UNDER,
TERMFONT_BI,
TERMFONT__MAX
};
struct eqn_box;
struct roff_meta;
struct roff_node;
struct tbl_span;
struct termp;
typedef void (*term_margin)(struct termp *, const struct roff_meta *);
struct termp_tbl {
int width; /* width in fixed chars */
int decimal; /* decimal point position */
};
struct termp_col {
int *buf; /* Output buffer. */
size_t maxcols; /* Allocated bytes in buf. */
size_t lastcol; /* Last byte in buf. */
size_t col; /* Byte in buf to be written. */
size_t rmargin; /* Current right margin. */
size_t offset; /* Current left margin. */
};
struct termp {
struct rofftbl tbl; /* Table configuration. */
struct termp_col *tcols; /* Array of table columns. */
struct termp_col *tcol; /* Current table column. */
size_t maxtcol; /* Allocated table columns. */
size_t lasttcol; /* Last column currently used. */
size_t line; /* Current output line number. */
size_t defindent; /* Default indent for text. */
size_t defrmargin; /* Right margin of the device. */
size_t lastrmargin; /* Right margin before the last ll. */
size_t maxrmargin; /* Max right margin. */
size_t col; /* Byte position in buf. */
size_t viscol; /* Chars on current line. */
size_t trailspace; /* See term_flushln(). */
size_t minbl; /* Minimum blanks before next field. */
int synopsisonly; /* Print the synopsis only. */
int mdocstyle; /* Imitate mdoc(7) output. */
int ti; /* Temporary indent for one line. */
int skipvsp; /* Vertical space to skip. */
int flags;
#define TERMP_SENTENCE (1 << 0) /* Space before a sentence. */
#define TERMP_NOSPACE (1 << 1) /* No space before words. */
#define TERMP_NONOSPACE (1 << 2) /* No space (no autounset). */
#define TERMP_NBRWORD (1 << 3) /* Make next word nonbreaking. */
#define TERMP_KEEP (1 << 4) /* Keep words together. */
#define TERMP_PREKEEP (1 << 5) /* ...starting with the next one. */
#define TERMP_BACKAFTER (1 << 6) /* Back up after next character. */
#define TERMP_BACKBEFORE (1 << 7) /* Back up before next character. */
#define TERMP_NOBREAK (1 << 8) /* See term_flushln(). */
#define TERMP_BRTRSP (1 << 9) /* See term_flushln(). */
#define TERMP_BRIND (1 << 10) /* See term_flushln(). */
#define TERMP_HANG (1 << 11) /* See term_flushln(). */
#define TERMP_NOPAD (1 << 12) /* See term_flushln(). */
#define TERMP_NOSPLIT (1 << 13) /* Do not break line before .An. */
#define TERMP_SPLIT (1 << 14) /* Break line before .An. */
#define TERMP_NONEWLINE (1 << 15) /* No line break in nofill mode. */
#define TERMP_BRNEVER (1 << 16) /* Don't even break at maxrmargin. */
#define TERMP_NOBUF (1 << 17) /* Bypass output buffer. */
#define TERMP_NEWMC (1 << 18) /* No .mc printed yet. */
#define TERMP_ENDMC (1 << 19) /* Next break ends .mc mode. */
#define TERMP_MULTICOL (1 << 20) /* Multiple column mode. */
enum termtype type; /* Terminal, PS, or PDF. */
enum termenc enc; /* Type of encoding. */
enum termfont fontl; /* Last font set. */
enum termfont *fontq; /* Symmetric fonts. */
int fontsz; /* Allocated size of font stack */
int fonti; /* Index of font stack. */
term_margin headf; /* invoked to print head */
term_margin footf; /* invoked to print foot */
void (*letter)(struct termp *, int);
void (*begin)(struct termp *);
void (*end)(struct termp *);
void (*endline)(struct termp *);
void (*advance)(struct termp *, size_t);
void (*setwidth)(struct termp *, int, int);
size_t (*width)(const struct termp *, int);
int (*hspan)(const struct termp *,
const struct roffsu *);
const void *argf; /* arg for headf/footf */
const char *mc; /* Margin character. */
struct termp_ps *ps;
};
const char *ascii_uc2str(int);
void roff_term_pre(struct termp *, const struct roff_node *);
void term_eqn(struct termp *, const struct eqn_box *);
void term_tbl(struct termp *, const struct tbl_span *);
void term_free(struct termp *);
void term_setcol(struct termp *, size_t);
void term_newln(struct termp *);
void term_vspace(struct termp *);
void term_word(struct termp *, const char *);
void term_flushln(struct termp *);
void term_begin(struct termp *, term_margin,
term_margin, const struct roff_meta *);
void term_end(struct termp *);
void term_setwidth(struct termp *, const char *);
int term_hspan(const struct termp *, const struct roffsu *);
int term_hen(const struct termp *, const struct roffsu *);
int term_vspan(const struct termp *, const struct roffsu *);
size_t term_strlen(const struct termp *, const char *);
size_t term_len(const struct termp *, size_t);
void term_tab_set(const struct termp *, const char *);
void term_tab_iset(size_t);
size_t term_tab_next(size_t);
void term_fontpush(struct termp *, enum termfont);
void term_fontpop(struct termp *);
void term_fontpopq(struct termp *, int);
void term_fontrepl(struct termp *, enum termfont);
void term_fontlast(struct termp *);
mandoc-1.14.3/att.c 0100644 0002007 0000011 00000003237 13141336266 0013417 0 ustar 00schwarze wsrc /* $Id: att.c,v 1.16 2017/06/24 14:38:32 schwarze Exp $ */
/*
* Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#include "config.h"
#include <sys/types.h>
#include <string.h>
#include "mandoc.h"
#include "roff.h"
#include "mdoc.h"
#include "libmdoc.h"
#define LINE(x, y) \
if (0 == strcmp(p, x)) return(y)
const char *
mdoc_a2att(const char *p)
{
LINE("v1", "Version\\~1 AT&T UNIX");
LINE("v2", "Version\\~2 AT&T UNIX");
LINE("v3", "Version\\~3 AT&T UNIX");
LINE("v4", "Version\\~4 AT&T UNIX");
LINE("v5", "Version\\~5 AT&T UNIX");
LINE("v6", "Version\\~6 AT&T UNIX");
LINE("v7", "Version\\~7 AT&T UNIX");
LINE("32v", "Version\\~32V AT&T UNIX");
LINE("III", "AT&T System\\~III UNIX");
LINE("V", "AT&T System\\~V UNIX");
LINE("V.1", "AT&T System\\~V Release\\~1 UNIX");
LINE("V.2", "AT&T System\\~V Release\\~2 UNIX");
LINE("V.3", "AT&T System\\~V Release\\~3 UNIX");
LINE("V.4", "AT&T System\\~V Release\\~4 UNIX");
return NULL;
}
mandoc-1.14.3/catman.c 0100644 0002007 0000011 00000013026 13141336266 0014067 0 ustar 00schwarze wsrc /* $Id: catman.c,v 1.21 2017/02/18 12:24:24 schwarze Exp $ */
/*
* Copyright (c) 2017 Michael Stapelberg <stapelberg@debian.org>
* Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#include "config.h"
#if HAVE_CMSG_XPG42
#define _XPG4_2
#endif
#include <sys/types.h>
#include <sys/socket.h>
#include <sys/stat.h>
#if HAVE_ERR
#include <err.h>
#endif
#include <errno.h>
#include <fcntl.h>
#if HAVE_FTS
#include <fts.h>
#else
#include "compat_fts.h"
#endif
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <unistd.h>
int process_manpage(int, int, const char *);
int process_tree(int, int);
void run_mandocd(int, const char *, const char *)
__attribute__((__noreturn__));
ssize_t sock_fd_write(int, int, int, int);
void usage(void) __attribute__((__noreturn__));
void
run_mandocd(int sockfd, const char *outtype, const char* defos)
{
char sockfdstr[10];
if (snprintf(sockfdstr, sizeof(sockfdstr), "%d", sockfd) == -1)
err(1, "snprintf");
if (defos == NULL)
execlp("mandocd", "mandocd", "-T", outtype,
sockfdstr, (char *)NULL);
else
execlp("mandocd", "mandocd", "-T", outtype,
"-I", defos, sockfdstr, (char *)NULL);
err(1, "exec");
}
ssize_t
sock_fd_write(int fd, int fd0, int fd1, int fd2)
{
const struct timespec timeout = { 0, 10000000 }; /* 0.01 s */
struct msghdr msg;
struct iovec iov;
union {
struct cmsghdr cmsghdr;
char control[CMSG_SPACE(3 * sizeof(int))];
} cmsgu;
struct cmsghdr *cmsg;
int *walk;
ssize_t sz;
unsigned char dummy[1] = {'\0'};
iov.iov_base = dummy;
iov.iov_len = sizeof(dummy);
msg.msg_name = NULL;
msg.msg_namelen = 0;
msg.msg_iov = &iov;
msg.msg_iovlen = 1;
msg.msg_control = cmsgu.control;
msg.msg_controllen = sizeof(cmsgu.control);
cmsg = CMSG_FIRSTHDR(&msg);
cmsg->cmsg_len = CMSG_LEN(3 * sizeof(int));
cmsg->cmsg_level = SOL_SOCKET;
cmsg->cmsg_type = SCM_RIGHTS;
walk = (int *)CMSG_DATA(cmsg);
*(walk++) = fd0;
*(walk++) = fd1;
*(walk++) = fd2;
/*
* It appears that on some systems, sendmsg(3)
* may return EAGAIN even in blocking mode.
* Seen for example on Oracle Solaris 11.2.
* The sleeping time was chosen by experimentation,
* to neither cause more than a handful of retries
* in normal operation nor unnecessary delays.
*/
for (;;) {
if ((sz = sendmsg(fd, &msg, 0)) != -1 ||
errno != EAGAIN)
break;
nanosleep(&timeout, NULL);
}
return sz;
}
int
process_manpage(int srv_fd, int dstdir_fd, const char *path)
{
int in_fd, out_fd;
int irc;
if ((in_fd = open(path, O_RDONLY)) == -1) {
warn("open(%s)", path);
return 0;
}
if ((out_fd = openat(dstdir_fd, path,
O_WRONLY | O_NOFOLLOW | O_CREAT | O_TRUNC,
S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) {
warn("openat(%s)", path);
close(in_fd);
return 0;
}
irc = sock_fd_write(srv_fd, in_fd, out_fd, STDERR_FILENO);
close(in_fd);
close(out_fd);
if (irc < 0) {
warn("sendmsg");
return -1;
}
return 0;
}
int
process_tree(int srv_fd, int dstdir_fd)
{
FTS *ftsp;
FTSENT *entry;
const char *argv[2];
const char *path;
argv[0] = ".";
argv[1] = (char *)NULL;
if ((ftsp = fts_open((char * const *)argv,
FTS_PHYSICAL | FTS_NOCHDIR, NULL)) == NULL) {
warn("fts_open");
return -1;
}
while ((entry = fts_read(ftsp)) != NULL) {
path = entry->fts_path + 2;
switch (entry->fts_info) {
case FTS_F:
if (process_manpage(srv_fd, dstdir_fd, path) == -1) {
fts_close(ftsp);
return -1;
}
break;
case FTS_D:
if (*path != '\0' &&
mkdirat(dstdir_fd, path, S_IRWXU | S_IRGRP |
S_IXGRP | S_IROTH | S_IXOTH) == -1 &&
errno != EEXIST) {
warn("mkdirat(%s)", path);
(void)fts_set(ftsp, entry, FTS_SKIP);
}
break;
case FTS_DP:
break;
default:
warnx("%s: not a regular file", path);
break;
}
}
fts_close(ftsp);
return 0;
}
int
main(int argc, char **argv)
{
const char *defos, *outtype;
int srv_fds[2];
int dstdir_fd;
int opt;
pid_t pid;
defos = NULL;
outtype = "ascii";
while ((opt = getopt(argc, argv, "I:T:")) != -1) {
switch (opt) {
case 'I':
defos = optarg;
break;
case 'T':
outtype = optarg;
break;
default:
usage();
}
}
if (argc > 0) {
argc -= optind;
argv += optind;
}
if (argc != 2)
usage();
if (socketpair(AF_LOCAL, SOCK_STREAM, AF_UNSPEC, srv_fds) == -1)
err(1, "socketpair");
pid = fork();
switch (pid) {
case -1:
err(1, "fork");
case 0:
close(srv_fds[0]);
run_mandocd(srv_fds[1], outtype, defos);
default:
break;
}
close(srv_fds[1]);
if ((dstdir_fd = open(argv[1], O_RDONLY | O_DIRECTORY)) == -1)
err(1, "open(%s)", argv[1]);
if (chdir(argv[0]) == -1)
err(1, "chdir(%s)", argv[0]);
return process_tree(srv_fds[0], dstdir_fd) == -1 ? 1 : 0;
}
void
usage(void)
{
fprintf(stderr, "usage: %s [-I os=name] [-T output] "
"srcdir dstdir\n", BINM_CATMAN);
exit(1);
}
mandoc-1.14.3/cgi.c 0100644 0002007 0000011 00000065643 13141336266 0013402 0 ustar 00schwarze wsrc /* $Id: cgi.c,v 1.156 2017/06/24 14:38:32 schwarze Exp $ */
/*
* Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
* Copyright (c) 2014, 2015, 2016, 2017 Ingo Schwarze <schwarze@usta.de>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#include "config.h"
#include <sys/types.h>
#include <sys/time.h>
#include <ctype.h>
#if HAVE_ERR
#include <err.h>
#endif
#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include "mandoc_aux.h"
#include "mandoc.h"
#include "roff.h"
#include "mdoc.h"
#include "man.h"
#include "main.h"
#include "manconf.h"
#include "mansearch.h"
#include "cgi.h"
/*
* A query as passed to the search function.
*/
struct query {
char *manpath; /* desired manual directory */
char *arch; /* architecture */
char *sec; /* manual section */
char *query; /* unparsed query expression */
int equal; /* match whole names, not substrings */
};
struct req {
struct query q;
char **p; /* array of available manpaths */
size_t psz; /* number of available manpaths */
int isquery; /* QUERY_STRING used, not PATH_INFO */
};
enum focus {
FOCUS_NONE = 0,
FOCUS_QUERY
};
static void html_print(const char *);
static void html_putchar(char);
static int http_decode(char *);
static void parse_manpath_conf(struct req *);
static void parse_path_info(struct req *req, const char *path);
static void parse_query_string(struct req *, const char *);
static void pg_error_badrequest(const char *);
static void pg_error_internal(void);
static void pg_index(const struct req *);
static void pg_noresult(const struct req *, const char *);
static void pg_redirect(const struct req *, const char *);
static void pg_search(const struct req *);
static void pg_searchres(const struct req *,
struct manpage *, size_t);
static void pg_show(struct req *, const char *);
static void resp_begin_html(int, const char *, const char *);
static void resp_begin_http(int, const char *);
static void resp_catman(const struct req *, const char *);
static void resp_copy(const char *);
static void resp_end_html(void);
static void resp_format(const struct req *, const char *);
static void resp_searchform(const struct req *, enum focus);
static void resp_show(const struct req *, const char *);
static void set_query_attr(char **, char **);
static int validate_filename(const char *);
static int validate_manpath(const struct req *, const char *);
static int validate_urifrag(const char *);
static const char *scriptname = SCRIPT_NAME;
static const int sec_prios[] = {1, 4, 5, 8, 6, 3, 7, 2, 9};
static const char *const sec_numbers[] = {
"0", "1", "2", "3", "3p", "4", "5", "6", "7", "8", "9"
};
static const char *const sec_names[] = {
"All Sections",
"1 - General Commands",
"2 - System Calls",
"3 - Library Functions",
"3p - Perl Library",
"4 - Device Drivers",
"5 - File Formats",
"6 - Games",
"7 - Miscellaneous Information",
"8 - System Manager\'s Manual",
"9 - Kernel Developer\'s Manual"
};
static const int sec_MAX = sizeof(sec_names) / sizeof(char *);
static const char *const arch_names[] = {
"amd64", "alpha", "armv7", "arm64",
"hppa", "i386", "landisk",
"loongson", "luna88k", "macppc", "mips64",
"octeon", "sgi", "socppc", "sparc64",
"amiga", "arc", "armish", "arm32",
"atari", "aviion", "beagle", "cats",
"hppa64", "hp300",
"ia64", "mac68k", "mvme68k", "mvme88k",
"mvmeppc", "palm", "pc532", "pegasos",
"pmax", "powerpc", "solbourne", "sparc",
"sun3", "vax", "wgrisc", "x68k",
"zaurus"
};
static const int arch_MAX = sizeof(arch_names) / sizeof(char *);
/*
* Print a character, escaping HTML along the way.
* This will pass non-ASCII straight to output: be warned!
*/
static void
html_putchar(char c)
{
switch (c) {
case '"':
printf(""");
break;
case '&':
printf("&");
break;
case '>':
printf(">");
break;
case '<':
printf("<");
break;
default:
putchar((unsigned char)c);
break;
}
}
/*
* Call through to html_putchar().
* Accepts NULL strings.
*/
static void
html_print(const char *p)
{
if (NULL == p)
return;
while ('\0' != *p)
html_putchar(*p++);
}
/*
* Transfer the responsibility for the allocated string *val
* to the query structure.
*/
static void
set_query_attr(char **attr, char **val)
{
free(*attr);
if (**val == '\0') {
*attr = NULL;
free(*val);
} else
*attr = *val;
*val = NULL;
}
/*
* Parse the QUERY_STRING for key-value pairs
* and store the values into the query structure.
*/
static void
parse_query_string(struct req *req, const char *qs)
{
char *key, *val;
size_t keysz, valsz;
req->isquery = 1;
req->q.manpath = NULL;
req->q.arch = NULL;
req->q.sec = NULL;
req->q.query = NULL;
req->q.equal = 1;
key = val = NULL;
while (*qs != '\0') {
/* Parse one key. */
keysz = strcspn(qs, "=;&");
key = mandoc_strndup(qs, keysz);
qs += keysz;
if (*qs != '=')
goto next;
/* Parse one value. */
valsz = strcspn(++qs, ";&");
val = mandoc_strndup(qs, valsz);
qs += valsz;
/* Decode and catch encoding errors. */
if ( ! (http_decode(key) && http_decode(val)))
goto next;
/* Handle key-value pairs. */
if ( ! strcmp(key, "query"))
set_query_attr(&req->q.query, &val);
else if ( ! strcmp(key, "apropos"))
req->q.equal = !strcmp(val, "0");
else if ( ! strcmp(key, "manpath")) {
#ifdef COMPAT_OLDURI
if ( ! strncmp(val, "OpenBSD ", 8)) {
val[7] = '-';
if ('C' == val[8])
val[8] = 'c';
}
#endif
set_query_attr(&req->q.manpath, &val);
}
else if ( ! (strcmp(key, "sec")
#ifdef COMPAT_OLDURI
&& strcmp(key, "sektion")
#endif
)) {
if ( ! strcmp(val, "0"))
*val = '\0';
set_query_attr(&req->q.sec, &val);
}
else if ( ! strcmp(key, "arch")) {
if ( ! strcmp(val, "default"))
*val = '\0';
set_query_attr(&req->q.arch, &val);
}
/*
* The key must be freed in any case.
* The val may have been handed over to the query
* structure, in which case it is now NULL.
*/
next:
free(key);
key = NULL;
free(val);
val = NULL;
if (*qs != '\0')
qs++;
}
}
/*
* HTTP-decode a string. The standard explanation is that this turns
* "%4e+foo" into "n foo" in the regular way. This is done in-place
* over the allocated string.
*/
static int
http_decode(char *p)
{
char hex[3];
char *q;
int c;
hex[2] = '\0';
q = p;
for ( ; '\0' != *p; p++, q++) {
if ('%' == *p) {
if ('\0' == (hex[0] = *(p + 1)))
return 0;
if ('\0' == (hex[1] = *(p + 2)))
return 0;
if (1 != sscanf(hex, "%x", &c))
return 0;
if ('\0' == c)
return 0;
*q = (char)c;
p += 2;
} else
*q = '+' == *p ? ' ' : *p;
}
*q = '\0';
return 1;
}
static void
resp_begin_http(int code, const char *msg)
{
if (200 != code)
printf("Status: %d %s\r\n", code, msg);
printf("Content-Type: text/html; charset=utf-8\r\n"
"Cache-Control: no-cache\r\n"
"Pragma: no-cache\r\n"
"\r\n");
fflush(stdout);
}
static void
resp_copy(const char *filename)
{
char buf[4096];
ssize_t sz;
int fd;
if ((fd = open(filename, O_RDONLY)) != -1) {
fflush(stdout);
while ((sz = read(fd, buf, sizeof(buf))) > 0)
write(STDOUT_FILENO, buf, sz);
close(fd);
}
}
static void
resp_begin_html(int code, const char *msg, const char *file)
{
char *cp;
resp_begin_http(code, msg);
printf("<!DOCTYPE html>\n"
"<html>\n"
"<head>\n"
" <meta charset=\"UTF-8\"/>\n"
" <link rel=\"stylesheet\" href=\"%s/mandoc.css\""
" type=\"text/css\" media=\"all\">\n"
" <title>",
CSS_DIR);
if (file != NULL) {
if ((cp = strrchr(file, '/')) != NULL)
file = cp + 1;
if ((cp = strrchr(file, '.')) != NULL) {
printf("%.*s(%s) - ", (int)(cp - file), file, cp + 1);
} else
printf("%s - ", file);
}
printf("%s\n"
"\n"
"\n",
CUSTOMIZE_TITLE);
resp_copy(MAN_DIR "/header.html");
}
static void
resp_end_html(void)
{
resp_copy(MAN_DIR "/footer.html");
puts("\n"
"");
}
static void
resp_searchform(const struct req *req, enum focus focus)
{
int i;
printf("");
}
static int
validate_urifrag(const char *frag)
{
while ('\0' != *frag) {
if ( ! (isalnum((unsigned char)*frag) ||
'-' == *frag || '.' == *frag ||
'/' == *frag || '_' == *frag))
return 0;
frag++;
}
return 1;
}
static int
validate_manpath(const struct req *req, const char* manpath)
{
size_t i;
for (i = 0; i < req->psz; i++)
if ( ! strcmp(manpath, req->p[i]))
return 1;
return 0;
}
static int
validate_filename(const char *file)
{
if ('.' == file[0] && '/' == file[1])
file += 2;
return ! (strstr(file, "../") || strstr(file, "/..") ||
(strncmp(file, "man", 3) && strncmp(file, "cat", 3)));
}
static void
pg_index(const struct req *req)
{
resp_begin_html(200, NULL, NULL);
resp_searchform(req, FOCUS_QUERY);
printf("\n"
"This web interface is documented in the\n"
"man.cgi(8)\n"
"manual, and the\n"
"apropos(1)\n"
"manual explains the query syntax.\n"
"
\n",
scriptname, *scriptname == '\0' ? "" : "/",
scriptname, *scriptname == '\0' ? "" : "/");
resp_end_html();
}
static void
pg_noresult(const struct req *req, const char *msg)
{
resp_begin_html(200, NULL, NULL);
resp_searchform(req, FOCUS_QUERY);
puts("");
puts(msg);
puts("
");
resp_end_html();
}
static void
pg_error_badrequest(const char *msg)
{
resp_begin_html(400, "Bad Request", NULL);
puts("Bad Request
\n"
"\n");
puts(msg);
printf("Try again from the\n"
"main page.\n"
"
", scriptname);
resp_end_html();
}
static void
pg_error_internal(void)
{
resp_begin_html(500, "Internal Server Error", NULL);
puts("Internal Server Error
");
resp_end_html();
}
static void
pg_redirect(const struct req *req, const char *name)
{
printf("Status: 303 See Other\r\n"
"Location: /");
if (*scriptname != '\0')
printf("%s/", scriptname);
if (strcmp(req->q.manpath, req->p[0]))
printf("%s/", req->q.manpath);
if (req->q.arch != NULL)
printf("%s/", req->q.arch);
printf("%s", name);
if (req->q.sec != NULL)
printf(".%s", req->q.sec);
printf("\r\nContent-Type: text/html; charset=utf-8\r\n\r\n");
}
static void
pg_searchres(const struct req *req, struct manpage *r, size_t sz)
{
char *arch, *archend;
const char *sec;
size_t i, iuse;
int archprio, archpriouse;
int prio, priouse;
for (i = 0; i < sz; i++) {
if (validate_filename(r[i].file))
continue;
warnx("invalid filename %s in %s database",
r[i].file, req->q.manpath);
pg_error_internal();
return;
}
if (req->isquery && sz == 1) {
/*
* If we have just one result, then jump there now
* without any delay.
*/
printf("Status: 303 See Other\r\n"
"Location: /");
if (*scriptname != '\0')
printf("%s/", scriptname);
if (strcmp(req->q.manpath, req->p[0]))
printf("%s/", req->q.manpath);
printf("%s\r\n"
"Content-Type: text/html; charset=utf-8\r\n\r\n",
r[0].file);
return;
}
/*
* In man(1) mode, show one of the pages
* even if more than one is found.
*/
iuse = 0;
if (req->q.equal || sz == 1) {
priouse = 20;
archpriouse = 3;
for (i = 0; i < sz; i++) {
sec = r[i].file;
sec += strcspn(sec, "123456789");
if (sec[0] == '\0')
continue;
prio = sec_prios[sec[0] - '1'];
if (sec[1] != '/')
prio += 10;
if (req->q.arch == NULL) {
archprio =
((arch = strchr(sec + 1, '/'))
== NULL) ? 3 :
((archend = strchr(arch + 1, '/'))
== NULL) ? 0 :
strncmp(arch, "amd64/",
archend - arch) ? 2 : 1;
if (archprio < archpriouse) {
archpriouse = archprio;
priouse = prio;
iuse = i;
continue;
}
if (archprio > archpriouse)
continue;
}
if (prio >= priouse)
continue;
priouse = prio;
iuse = i;
}
resp_begin_html(200, NULL, r[iuse].file);
} else
resp_begin_html(200, NULL, NULL);
resp_searchform(req,
req->q.equal || sz == 1 ? FOCUS_NONE : FOCUS_QUERY);
if (sz > 1) {
puts("");
}
if (req->q.equal || sz == 1) {
puts("
");
resp_show(req, r[iuse].file);
}
resp_end_html();
}
static void
resp_catman(const struct req *req, const char *file)
{
FILE *f;
char *p;
size_t sz;
ssize_t len;
int i;
int italic, bold;
if ((f = fopen(file, "r")) == NULL) {
puts("You specified an invalid manual file.
");
return;
}
puts("\n"
"
");
p = NULL;
sz = 0;
while ((len = getline(&p, &sz, f)) != -1) {
bold = italic = 0;
for (i = 0; i < len - 1; i++) {
/*
* This means that the catpage is out of state.
* Ignore it and keep going (although the
* catpage is bogus).
*/
if ('\b' == p[i] || '\n' == p[i])
continue;
/*
* Print a regular character.
* Close out any bold/italic scopes.
* If we're in back-space mode, make sure we'll
* have something to enter when we backspace.
*/
if ('\b' != p[i + 1]) {
if (italic)
printf("");
if (bold)
printf("");
italic = bold = 0;
html_putchar(p[i]);
continue;
} else if (i + 2 >= len)
continue;
/* Italic mode. */
if ('_' == p[i]) {
if (bold)
printf("");
if ( ! italic)
printf("");
bold = 0;
italic = 1;
i += 2;
html_putchar(p[i]);
continue;
}
/*
* Handle funny behaviour troff-isms.
* These grok'd from the original man2html.c.
*/
if (('+' == p[i] && 'o' == p[i + 2]) ||
('o' == p[i] && '+' == p[i + 2]) ||
('|' == p[i] && '=' == p[i + 2]) ||
('=' == p[i] && '|' == p[i + 2]) ||
('*' == p[i] && '=' == p[i + 2]) ||
('=' == p[i] && '*' == p[i + 2]) ||
('*' == p[i] && '|' == p[i + 2]) ||
('|' == p[i] && '*' == p[i + 2])) {
if (italic)
printf("");
if (bold)
printf("");
italic = bold = 0;
putchar('*');
i += 2;
continue;
} else if (('|' == p[i] && '-' == p[i + 2]) ||
('-' == p[i] && '|' == p[i + 1]) ||
('+' == p[i] && '-' == p[i + 1]) ||
('-' == p[i] && '+' == p[i + 1]) ||
('+' == p[i] && '|' == p[i + 1]) ||
('|' == p[i] && '+' == p[i + 1])) {
if (italic)
printf("");
if (bold)
printf("");
italic = bold = 0;
putchar('+');
i += 2;
continue;
}
/* Bold mode. */
if (italic)
printf("");
if ( ! bold)
printf("");
bold = 1;
italic = 0;
i += 2;
html_putchar(p[i]);
}
/*
* Clean up the last character.
* We can get to a newline; don't print that.
*/
if (italic)
printf("");
if (bold)
printf("");
if (i == len - 1 && p[i] != '\n')
html_putchar(p[i]);
putchar('\n');
}
free(p);
puts("\n"
"
You specified an invalid manual file.
");
return;
}
mchars_alloc();
mp = mparse_alloc(MPARSE_SO | MPARSE_UTF8 | MPARSE_LATIN1,
MANDOCERR_MAX, NULL, MANDOC_OS_OTHER, req->q.manpath);
mparse_readfd(mp, fd, file);
close(fd);
memset(&conf, 0, sizeof(conf));
conf.fragment = 1;
conf.style = mandoc_strdup(CSS_DIR "/mandoc.css");
usepath = strcmp(req->q.manpath, req->p[0]);
mandoc_asprintf(&conf.man, "/%s%s%s%s%%N.%%S",
scriptname, *scriptname == '\0' ? "" : "/",
usepath ? req->q.manpath : "", usepath ? "/" : "");
mparse_result(mp, &man, NULL);
if (man == NULL) {
warnx("fatal mandoc error: %s/%s", req->q.manpath, file);
pg_error_internal();
mparse_free(mp);
mchars_free();
return;
}
vp = html_alloc(&conf);
if (man->macroset == MACROSET_MDOC) {
mdoc_validate(man);
html_mdoc(vp, man);
} else {
man_validate(man);
html_man(vp, man);
}
html_free(vp);
mparse_free(mp);
mchars_free();
free(conf.man);
free(conf.style);
}
static void
resp_show(const struct req *req, const char *file)
{
if ('.' == file[0] && '/' == file[1])
file += 2;
if ('c' == *file)
resp_catman(req, file);
else
resp_format(req, file);
}
static void
pg_show(struct req *req, const char *fullpath)
{
char *manpath;
const char *file;
if ((file = strchr(fullpath, '/')) == NULL) {
pg_error_badrequest(
"You did not specify a page to show.");
return;
}
manpath = mandoc_strndup(fullpath, file - fullpath);
file++;
if ( ! validate_manpath(req, manpath)) {
pg_error_badrequest(
"You specified an invalid manpath.");
free(manpath);
return;
}
/*
* Begin by chdir()ing into the manpath.
* This way we can pick up the database files, which are
* relative to the manpath root.
*/
if (chdir(manpath) == -1) {
warn("chdir %s", manpath);
pg_error_internal();
free(manpath);
return;
}
free(manpath);
if ( ! validate_filename(file)) {
pg_error_badrequest(
"You specified an invalid manual file.");
return;
}
resp_begin_html(200, NULL, file);
resp_searchform(req, FOCUS_NONE);
resp_show(req, file);
resp_end_html();
}
static void
pg_search(const struct req *req)
{
struct mansearch search;
struct manpaths paths;
struct manpage *res;
char **argv;
char *query, *rp, *wp;
size_t ressz;
int argc;
/*
* Begin by chdir()ing into the root of the manpath.
* This way we can pick up the database files, which are
* relative to the manpath root.
*/
if (chdir(req->q.manpath) == -1) {
warn("chdir %s", req->q.manpath);
pg_error_internal();
return;
}
search.arch = req->q.arch;
search.sec = req->q.sec;
search.outkey = "Nd";
search.argmode = req->q.equal ? ARG_NAME : ARG_EXPR;
search.firstmatch = 1;
paths.sz = 1;
paths.paths = mandoc_malloc(sizeof(char *));
paths.paths[0] = mandoc_strdup(".");
/*
* Break apart at spaces with backslash-escaping.
*/
argc = 0;
argv = NULL;
rp = query = mandoc_strdup(req->q.query);
for (;;) {
while (isspace((unsigned char)*rp))
rp++;
if (*rp == '\0')
break;
argv = mandoc_reallocarray(argv, argc + 1, sizeof(char *));
argv[argc++] = wp = rp;
for (;;) {
if (isspace((unsigned char)*rp)) {
*wp = '\0';
rp++;
break;
}
if (rp[0] == '\\' && rp[1] != '\0')
rp++;
if (wp != rp)
*wp = *rp;
if (*rp == '\0')
break;
wp++;
rp++;
}
}
res = NULL;
ressz = 0;
if (req->isquery && req->q.equal && argc == 1)
pg_redirect(req, argv[0]);
else if (mansearch(&search, &paths, argc, argv, &res, &ressz) == 0)
pg_noresult(req, "You entered an invalid query.");
else if (ressz == 0)
pg_noresult(req, "No results found.");
else
pg_searchres(req, res, ressz);
free(query);
mansearch_free(res, ressz);
free(paths.paths[0]);
free(paths.paths);
}
int
main(void)
{
struct req req;
struct itimerval itimer;
const char *path;
const char *querystring;
int i;
#if HAVE_PLEDGE
/*
* The "rpath" pledge could be revoked after mparse_readfd()
* if the file desciptor to "/footer.html" would be opened
* up front, but it's probably not worth the complication
* of the code it would cause: it would require scattering
* pledge() calls in multiple low-level resp_*() functions.
*/
if (pledge("stdio rpath", NULL) == -1) {
warn("pledge");
pg_error_internal();
return EXIT_FAILURE;
}
#endif
/* Poor man's ReDoS mitigation. */
itimer.it_value.tv_sec = 2;
itimer.it_value.tv_usec = 0;
itimer.it_interval.tv_sec = 2;
itimer.it_interval.tv_usec = 0;
if (setitimer(ITIMER_VIRTUAL, &itimer, NULL) == -1) {
warn("setitimer");
pg_error_internal();
return EXIT_FAILURE;
}
/*
* First we change directory into the MAN_DIR so that
* subsequent scanning for manpath directories is rooted
* relative to the same position.
*/
if (chdir(MAN_DIR) == -1) {
warn("MAN_DIR: %s", MAN_DIR);
pg_error_internal();
return EXIT_FAILURE;
}
memset(&req, 0, sizeof(struct req));
req.q.equal = 1;
parse_manpath_conf(&req);
/* Parse the path info and the query string. */
if ((path = getenv("PATH_INFO")) == NULL)
path = "";
else if (*path == '/')
path++;
if (*path != '\0') {
parse_path_info(&req, path);
if (req.q.manpath == NULL || req.q.sec == NULL ||
*req.q.query == '\0' || access(path, F_OK) == -1)
path = "";
} else if ((querystring = getenv("QUERY_STRING")) != NULL)
parse_query_string(&req, querystring);
/* Validate parsed data and add defaults. */
if (req.q.manpath == NULL)
req.q.manpath = mandoc_strdup(req.p[0]);
else if ( ! validate_manpath(&req, req.q.manpath)) {
pg_error_badrequest(
"You specified an invalid manpath.");
return EXIT_FAILURE;
}
if ( ! (NULL == req.q.arch || validate_urifrag(req.q.arch))) {
pg_error_badrequest(
"You specified an invalid architecture.");
return EXIT_FAILURE;
}
/* Dispatch to the three different pages. */
if ('\0' != *path)
pg_show(&req, path);
else if (NULL != req.q.query)
pg_search(&req);
else
pg_index(&req);
free(req.q.manpath);
free(req.q.arch);
free(req.q.sec);
free(req.q.query);
for (i = 0; i < (int)req.psz; i++)
free(req.p[i]);
free(req.p);
return EXIT_SUCCESS;
}
/*
* If PATH_INFO is not a file name, translate it to a query.
*/
static void
parse_path_info(struct req *req, const char *path)
{
char *dir[4];
int i;
req->isquery = 0;
req->q.equal = 1;
req->q.manpath = mandoc_strdup(path);
req->q.arch = NULL;
/* Mandatory manual page name. */
if ((req->q.query = strrchr(req->q.manpath, '/')) == NULL) {
req->q.query = req->q.manpath;
req->q.manpath = NULL;
} else
*req->q.query++ = '\0';
/* Optional trailing section. */
if ((req->q.sec = strrchr(req->q.query, '.')) != NULL) {
if(isdigit((unsigned char)req->q.sec[1])) {
*req->q.sec++ = '\0';
req->q.sec = mandoc_strdup(req->q.sec);
} else
req->q.sec = NULL;
}
/* Handle the case of name[.section] only. */
if (req->q.manpath == NULL)
return;
req->q.query = mandoc_strdup(req->q.query);
/* Split directory components. */
dir[i = 0] = req->q.manpath;
while ((dir[i + 1] = strchr(dir[i], '/')) != NULL) {
if (++i == 3) {
pg_error_badrequest(
"You specified too many directory components.");
exit(EXIT_FAILURE);
}
*dir[i]++ = '\0';
}
/* Optional manpath. */
if ((i = validate_manpath(req, req->q.manpath)) == 0)
req->q.manpath = NULL;
else if (dir[1] == NULL)
return;
/* Optional section. */
if (strncmp(dir[i], "man", 3) == 0) {
free(req->q.sec);
req->q.sec = mandoc_strdup(dir[i++] + 3);
}
if (dir[i] == NULL) {
if (req->q.manpath == NULL)
free(dir[0]);
return;
}
if (dir[i + 1] != NULL) {
pg_error_badrequest(
"You specified an invalid directory component.");
exit(EXIT_FAILURE);
}
/* Optional architecture. */
if (i) {
req->q.arch = mandoc_strdup(dir[i]);
if (req->q.manpath == NULL)
free(dir[0]);
} else
req->q.arch = dir[0];
}
/*
* Scan for indexable paths.
*/
static void
parse_manpath_conf(struct req *req)
{
FILE *fp;
char *dp;
size_t dpsz;
ssize_t len;
if ((fp = fopen("manpath.conf", "r")) == NULL) {
warn("%s/manpath.conf", MAN_DIR);
pg_error_internal();
exit(EXIT_FAILURE);
}
dp = NULL;
dpsz = 0;
while ((len = getline(&dp, &dpsz, fp)) != -1) {
if (dp[len - 1] == '\n')
dp[--len] = '\0';
req->p = mandoc_realloc(req->p,
(req->psz + 1) * sizeof(char *));
if ( ! validate_urifrag(dp)) {
warnx("%s/manpath.conf contains "
"unsafe path \"%s\"", MAN_DIR, dp);
pg_error_internal();
exit(EXIT_FAILURE);
}
if (strchr(dp, '/') != NULL) {
warnx("%s/manpath.conf contains "
"path with slash \"%s\"", MAN_DIR, dp);
pg_error_internal();
exit(EXIT_FAILURE);
}
req->p[req->psz++] = dp;
dp = NULL;
dpsz = 0;
}
free(dp);
if (req->p == NULL) {
warnx("%s/manpath.conf is empty", MAN_DIR);
pg_error_internal();
exit(EXIT_FAILURE);
}
}
mandoc-1.14.3/chars.c 0100644 0002007 0000011 00000031776 13141336266 0013740 0 ustar 00schwarze wsrc /* $Id: chars.c,v 1.71 2017/06/14 20:57:07 schwarze Exp $ */
/*
* Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons
* Copyright (c) 2011, 2014, 2015, 2017 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#include "config.h"
#include
#include
#include
#include
#include
#include
#include
#include "mandoc.h"
#include "mandoc_aux.h"
#include "mandoc_ohash.h"
#include "libmandoc.h"
struct ln {
const char roffcode[16];
const char *ascii;
int unicode;
};
/* Special break control characters. */
static const char ascii_nbrsp[2] = { ASCII_NBRSP, '\0' };
static const char ascii_break[2] = { ASCII_BREAK, '\0' };
static struct ln lines[] = {
/* Spacing. */
{ " ", ascii_nbrsp, 0x00a0 },
{ "~", ascii_nbrsp, 0x00a0 },
{ "0", " ", 0x2002 },
{ "|", "", 0 },
{ "^", "", 0 },
{ "&", "", 0 },
{ "%", "", 0 },
{ ":", ascii_break, 0 },
/* XXX The following three do not really belong here. */
{ "t", "", 0 },
{ "c", "", 0 },
{ "}", "", 0 },
/* Lines. */
{ "ba", "|", 0x007c },
{ "br", "|", 0x2502 },
{ "ul", "_", 0x005f },
{ "ru", "_", 0x005f },
{ "rn", "-", 0x203e },
{ "bb", "|", 0x00a6 },
{ "sl", "/", 0x002f },
{ "rs", "\\", 0x005c },
/* Text markers. */
{ "ci", "O", 0x25cb },
{ "bu", "+\bo", 0x2022 },
{ "dd", "|\b=", 0x2021 },
{ "dg", "|\b-", 0x2020 },
{ "lz", "<>", 0x25ca },
{ "sq", "[]", 0x25a1 },
{ "ps", "", 0x00b6 },
{ "sc", "", 0x00a7 },
{ "lh", "<=", 0x261c },
{ "rh", "=>", 0x261e },
{ "at", "@", 0x0040 },
{ "sh", "#", 0x0023 },
{ "CR", "_|", 0x21b5 },
{ "OK", "\\/", 0x2713 },
{ "CL", "", 0x2663 },
{ "SP", "", 0x2660 },
{ "HE", "", 0x2665 },
{ "DI", "", 0x2666 },
/* Legal symbols. */
{ "co", "(C)", 0x00a9 },
{ "rg", "(R)", 0x00ae },
{ "tm", "tm", 0x2122 },
/* Punctuation. */
{ "em", "--", 0x2014 },
{ "en", "-", 0x2013 },
{ "hy", "-", 0x2010 },
{ "e", "\\", 0x005c },
{ ".", ".", 0x002e },
{ "r!", "!", 0x00a1 },
{ "r?", "?", 0x00bf },
/* Quotes. */
{ "Bq", ",,", 0x201e },
{ "bq", ",", 0x201a },
{ "lq", "\"", 0x201c },
{ "rq", "\"", 0x201d },
{ "Lq", "\"", 0x201c },
{ "Rq", "\"", 0x201d },
{ "oq", "`", 0x2018 },
{ "cq", "\'", 0x2019 },
{ "aq", "\'", 0x0027 },
{ "dq", "\"", 0x0022 },
{ "Fo", "<<", 0x00ab },
{ "Fc", ">>", 0x00bb },
{ "fo", "<", 0x2039 },
{ "fc", ">", 0x203a },
/* Brackets. */
{ "lB", "[", 0x005b },
{ "rB", "]", 0x005d },
{ "lC", "{", 0x007b },
{ "rC", "}", 0x007d },
{ "la", "<", 0x27e8 },
{ "ra", ">", 0x27e9 },
{ "bv", "|", 0x23aa },
{ "braceex", "|", 0x23aa },
{ "bracketlefttp", "|", 0x23a1 },
{ "bracketleftbt", "|", 0x23a3 },
{ "bracketleftex", "|", 0x23a2 },
{ "bracketrighttp", "|", 0x23a4 },
{ "bracketrightbt", "|", 0x23a6 },
{ "bracketrightex", "|", 0x23a5 },
{ "lt", ",-", 0x23a7 },
{ "bracelefttp", ",-", 0x23a7 },
{ "lk", "{", 0x23a8 },
{ "braceleftmid", "{", 0x23a8 },
{ "lb", "`-", 0x23a9 },
{ "braceleftbt", "`-", 0x23a9 },
{ "braceleftex", "|", 0x23aa },
{ "rt", "-.", 0x23ab },
{ "bracerighttp", "-.", 0x23ab },
{ "rk", "}", 0x23ac },
{ "bracerightmid", "}", 0x23ac },
{ "rb", "-\'", 0x23ad },
{ "bracerightbt", "-\'", 0x23ad },
{ "bracerightex", "|", 0x23aa },
{ "parenlefttp", "/", 0x239b },
{ "parenleftbt", "\\", 0x239d },
{ "parenleftex", "|", 0x239c },
{ "parenrighttp", "\\", 0x239e },
{ "parenrightbt", "/", 0x23a0 },
{ "parenrightex", "|", 0x239f },
/* Arrows and lines. */
{ "<-", "<-", 0x2190 },
{ "->", "->", 0x2192 },
{ "<>", "<->", 0x2194 },
{ "da", "|\bv", 0x2193 },
{ "ua", "|\b^", 0x2191 },
{ "va", "^v", 0x2195 },
{ "lA", "<=", 0x21d0 },
{ "rA", "=>", 0x21d2 },
{ "hA", "<=>", 0x21d4 },
{ "uA", "=\b^", 0x21d1 },
{ "dA", "=\bv", 0x21d3 },
{ "vA", "^=v", 0x21d5 },
{ "an", "-", 0x23af },
/* Logic. */
{ "AN", "^", 0x2227 },
{ "OR", "v", 0x2228 },
{ "no", "~", 0x00ac },
{ "tno", "~", 0x00ac },
{ "te", "3", 0x2203 },
{ "fa", "-\bV", 0x2200 },
{ "st", "-)", 0x220b },
{ "tf", ".:.", 0x2234 },
{ "3d", ".:.", 0x2234 },
{ "or", "|", 0x007c },
/* Mathematicals. */
{ "pl", "+", 0x002b },
{ "mi", "-", 0x2212 },
{ "-", "-", 0x002d },
{ "-+", "-+", 0x2213 },
{ "+-", "+-", 0x00b1 },
{ "t+-", "+-", 0x00b1 },
{ "pc", ".", 0x00b7 },
{ "md", ".", 0x22c5 },
{ "mu", "x", 0x00d7 },
{ "tmu", "x", 0x00d7 },
{ "c*", "O\bx", 0x2297 },
{ "c+", "O\b+", 0x2295 },
{ "di", "-:-", 0x00f7 },
{ "tdi", "-:-", 0x00f7 },
{ "f/", "/", 0x2044 },
{ "**", "*", 0x2217 },
{ "<=", "<=", 0x2264 },
{ ">=", ">=", 0x2265 },
{ "<<", "<<", 0x226a },
{ ">>", ">>", 0x226b },
{ "eq", "=", 0x003d },
{ "!=", "!=", 0x2260 },
{ "==", "==", 0x2261 },
{ "ne", "!==", 0x2262 },
{ "ap", "~", 0x223c },
{ "|=", "-~", 0x2243 },
{ "=~", "=~", 0x2245 },
{ "~~", "~~", 0x2248 },
{ "~=", "~=", 0x2248 },
{ "pt", "oc", 0x221d },
{ "es", "{}", 0x2205 },
{ "mo", "E", 0x2208 },
{ "nm", "!E", 0x2209 },
{ "sb", "(=", 0x2282 },
{ "nb", "(!=", 0x2284 },
{ "sp", "=)", 0x2283 },
{ "nc", "!=)", 0x2285 },
{ "ib", "(=\b_", 0x2286 },
{ "ip", "=\b_)", 0x2287 },
{ "ca", "(^)", 0x2229 },
{ "cu", "U", 0x222a },
{ "/_", "_\b/", 0x2220 },
{ "pp", "_\b|", 0x22a5 },
{ "is", "'\b,\bI", 0x222b },
{ "integral", "'\b,\bI", 0x222b },
{ "sum", "E", 0x2211 },
{ "product", "TT", 0x220f },
{ "coproduct", "U", 0x2210 },
{ "gr", "V", 0x2207 },
{ "sr", "\\/", 0x221a },
{ "sqrt", "\\/", 0x221a },
{ "lc", "|~", 0x2308 },
{ "rc", "~|", 0x2309 },
{ "lf", "|_", 0x230a },
{ "rf", "_|", 0x230b },
{ "if", "oo", 0x221e },
{ "Ah", "N", 0x2135 },
{ "Im", "I", 0x2111 },
{ "Re", "R", 0x211c },
{ "wp", "P", 0x2118 },
{ "pd", "a", 0x2202 },
{ "-h", "/h", 0x210f },
{ "hbar", "/h", 0x210f },
{ "12", "1/2", 0x00bd },
{ "14", "1/4", 0x00bc },
{ "34", "3/4", 0x00be },
{ "18", "1/8", 0x215B },
{ "38", "3/8", 0x215C },
{ "58", "5/8", 0x215D },
{ "78", "7/8", 0x215E },
{ "S1", "1", 0x00B9 },
{ "S2", "2", 0x00B2 },
{ "S3", "3", 0x00B3 },
/* Ligatures. */
{ "ff", "ff", 0xfb00 },
{ "fi", "fi", 0xfb01 },
{ "fl", "fl", 0xfb02 },
{ "Fi", "ffi", 0xfb03 },
{ "Fl", "ffl", 0xfb04 },
{ "AE", "AE", 0x00c6 },
{ "ae", "ae", 0x00e6 },
{ "OE", "OE", 0x0152 },
{ "oe", "oe", 0x0153 },
{ "ss", "ss", 0x00df },
{ "IJ", "IJ", 0x0132 },
{ "ij", "ij", 0x0133 },
/* Accents. */
{ "a\"", "\"", 0x02dd },
{ "a-", "-", 0x00af },
{ "a.", ".", 0x02d9 },
{ "a^", "^", 0x005e },
{ "aa", "\'", 0x00b4 },
{ "\'", "\'", 0x00b4 },
{ "ga", "`", 0x0060 },
{ "`", "`", 0x0060 },
{ "ab", "'\b`", 0x02d8 },
{ "ac", ",", 0x00b8 },
{ "ad", "\"", 0x00a8 },
{ "ah", "v", 0x02c7 },
{ "ao", "o", 0x02da },
{ "a~", "~", 0x007e },
{ "ho", ",", 0x02db },
{ "ha", "^", 0x005e },
{ "ti", "~", 0x007e },
/* Accented letters. */
{ "'A", "'\bA", 0x00c1 },
{ "'E", "'\bE", 0x00c9 },
{ "'I", "'\bI", 0x00cd },
{ "'O", "'\bO", 0x00d3 },
{ "'U", "'\bU", 0x00da },
{ "'a", "'\ba", 0x00e1 },
{ "'e", "'\be", 0x00e9 },
{ "'i", "'\bi", 0x00ed },
{ "'o", "'\bo", 0x00f3 },
{ "'u", "'\bu", 0x00fa },
{ "`A", "`\bA", 0x00c0 },
{ "`E", "`\bE", 0x00c8 },
{ "`I", "`\bI", 0x00cc },
{ "`O", "`\bO", 0x00d2 },
{ "`U", "`\bU", 0x00d9 },
{ "`a", "`\ba", 0x00e0 },
{ "`e", "`\be", 0x00e8 },
{ "`i", "`\bi", 0x00ec },
{ "`o", "`\bo", 0x00f2 },
{ "`u", "`\bu", 0x00f9 },
{ "~A", "~\bA", 0x00c3 },
{ "~N", "~\bN", 0x00d1 },
{ "~O", "~\bO", 0x00d5 },
{ "~a", "~\ba", 0x00e3 },
{ "~n", "~\bn", 0x00f1 },
{ "~o", "~\bo", 0x00f5 },
{ ":A", "\"\bA", 0x00c4 },
{ ":E", "\"\bE", 0x00cb },
{ ":I", "\"\bI", 0x00cf },
{ ":O", "\"\bO", 0x00d6 },
{ ":U", "\"\bU", 0x00dc },
{ ":a", "\"\ba", 0x00e4 },
{ ":e", "\"\be", 0x00eb },
{ ":i", "\"\bi", 0x00ef },
{ ":o", "\"\bo", 0x00f6 },
{ ":u", "\"\bu", 0x00fc },
{ ":y", "\"\by", 0x00ff },
{ "^A", "^\bA", 0x00c2 },
{ "^E", "^\bE", 0x00ca },
{ "^I", "^\bI", 0x00ce },
{ "^O", "^\bO", 0x00d4 },
{ "^U", "^\bU", 0x00db },
{ "^a", "^\ba", 0x00e2 },
{ "^e", "^\be", 0x00ea },
{ "^i", "^\bi", 0x00ee },
{ "^o", "^\bo", 0x00f4 },
{ "^u", "^\bu", 0x00fb },
{ ",C", ",\bC", 0x00c7 },
{ ",c", ",\bc", 0x00e7 },
{ "/L", "/\bL", 0x0141 },
{ "/l", "/\bl", 0x0142 },
{ "/O", "/\bO", 0x00d8 },
{ "/o", "/\bo", 0x00f8 },
{ "oA", "o\bA", 0x00c5 },
{ "oa", "o\ba", 0x00e5 },
/* Special letters. */
{ "-D", "-\bD", 0x00d0 },
{ "Sd", "d", 0x00f0 },
{ "TP", "Th", 0x00de },
{ "Tp", "th", 0x00fe },
{ ".i", "i", 0x0131 },
{ ".j", "j", 0x0237 },
/* Currency. */
{ "Do", "$", 0x0024 },
{ "ct", "/\bc", 0x00a2 },
{ "Eu", "EUR", 0x20ac },
{ "eu", "EUR", 0x20ac },
{ "Ye", "=\bY", 0x00a5 },
{ "Po", "GBP", 0x00a3 },
{ "Cs", "o\bx", 0x00a4 },
{ "Fn", ",\bf", 0x0192 },
/* Units. */
{ "de", "", 0x00b0 },
{ "%0", "%o", 0x2030 },
{ "fm", "\'", 0x2032 },
{ "sd", "''", 0x2033 },
{ "mc", ",\bu", 0x00b5 },
{ "Of", "_\ba", 0x00aa },
{ "Om", "_\bo", 0x00ba },
/* Greek characters. */
{ "*A", "A", 0x0391 },
{ "*B", "B", 0x0392 },
{ "*G", "G", 0x0393 },
{ "*D", "_\b/_\b\\", 0x0394 },
{ "*E", "E", 0x0395 },
{ "*Z", "Z", 0x0396 },
{ "*Y", "H", 0x0397 },
{ "*H", "-\bO", 0x0398 },
{ "*I", "I", 0x0399 },
{ "*K", "K", 0x039a },
{ "*L", "/\\", 0x039b },
{ "*M", "M", 0x039c },
{ "*N", "N", 0x039d },
{ "*C", "_\bH", 0x039e },
{ "*O", "O", 0x039f },
{ "*P", "TT", 0x03a0 },
{ "*R", "P", 0x03a1 },
{ "*S", "S", 0x03a3 },
{ "*T", "T", 0x03a4 },
{ "*U", "Y", 0x03a5 },
{ "*F", "I\bO", 0x03a6 },
{ "*X", "X", 0x03a7 },
{ "*Q", "I\bY", 0x03a8 },
{ "*W", "_\bO", 0x03a9 },
{ "*a", "a", 0x03b1 },
{ "*b", "B", 0x03b2 },
{ "*g", "y", 0x03b3 },
{ "*d", "d", 0x03b4 },
{ "*e", "e", 0x03b5 },
{ "*z", ",\bC", 0x03b6 },
{ "*y", "n", 0x03b7 },
{ "*h", "-\b0", 0x03b8 },
{ "*i", "i", 0x03b9 },
{ "*k", "k", 0x03ba },
{ "*l", ">\b\\", 0x03bb },
{ "*m", ",\bu", 0x03bc },
{ "*n", "v", 0x03bd },
{ "*c", ",\bE", 0x03be },
{ "*o", "o", 0x03bf },
{ "*p", "-\bn", 0x03c0 },
{ "*r", "p", 0x03c1 },
{ "*s", "-\bo", 0x03c3 },
{ "*t", "~\bt", 0x03c4 },
{ "*u", "u", 0x03c5 },
{ "*f", "|\bo", 0x03d5 },
{ "*x", "x", 0x03c7 },
{ "*q", "|\bu", 0x03c8 },
{ "*w", "w", 0x03c9 },
{ "+h", "-\b0", 0x03d1 },
{ "+f", "|\bo", 0x03c6 },
{ "+p", "-\bw", 0x03d6 },
{ "+e", "e", 0x03f5 },
{ "ts", "s", 0x03c2 },
};
static struct ohash mchars;
void
mchars_free(void)
{
ohash_delete(&mchars);
}
void
mchars_alloc(void)
{
size_t i;
unsigned int slot;
mandoc_ohash_init(&mchars, 9, offsetof(struct ln, roffcode));
for (i = 0; i < sizeof(lines)/sizeof(lines[0]); i++) {
slot = ohash_qlookup(&mchars, lines[i].roffcode);
assert(ohash_find(&mchars, slot) == NULL);
ohash_insert(&mchars, slot, lines + i);
}
}
int
mchars_spec2cp(const char *p, size_t sz)
{
const struct ln *ln;
const char *end;
end = p + sz;
ln = ohash_find(&mchars, ohash_qlookupi(&mchars, p, &end));
return ln != NULL ? ln->unicode : sz == 1 ? (unsigned char)*p : -1;
}
int
mchars_num2char(const char *p, size_t sz)
{
int i;
i = mandoc_strntoi(p, sz, 10);
return i >= 0 && i < 256 ? i : -1;
}
int
mchars_num2uc(const char *p, size_t sz)
{
int i;
i = mandoc_strntoi(p, sz, 16);
assert(i >= 0 && i <= 0x10FFFF);
return i;
}
const char *
mchars_spec2str(const char *p, size_t sz, size_t *rsz)
{
const struct ln *ln;
const char *end;
end = p + sz;
ln = ohash_find(&mchars, ohash_qlookupi(&mchars, p, &end));
if (ln == NULL) {
*rsz = 1;
return sz == 1 ? p : NULL;
}
*rsz = strlen(ln->ascii);
return ln->ascii;
}
const char *
mchars_uc2str(int uc)
{
size_t i;
for (i = 0; i < sizeof(lines)/sizeof(lines[0]); i++)
if (uc == lines[i].unicode)
return lines[i].ascii;
return "";
}
mandoc-1.14.3/compat_err.c 0100644 0002007 0000011 00000005264 13141336266 0014764 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_ERR
int dummy;
#else
/* $Id: compat_err.c,v 1.4 2015/11/26 07:42:11 schwarze Exp $ */
/*
* Copyright (c) 1993
* The Regents of the University of California. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the University nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*/
#include
#include
#include
#include
#include
static void vwarni(const char *, va_list);
static void vwarnxi(const char *, va_list);
static void
vwarnxi(const char *fmt, va_list ap)
{
fprintf(stderr, "%s: ", getprogname());
if (fmt != NULL)
vfprintf(stderr, fmt, ap);
}
static void
vwarni(const char *fmt, va_list ap)
{
int sverrno;
sverrno = errno;
vwarnxi(fmt, ap);
if (fmt != NULL)
fputs(": ", stderr);
fprintf(stderr, "%s\n", strerror(sverrno));
}
void
err(int eval, const char *fmt, ...)
{
va_list ap;
va_start(ap, fmt);
vwarni(fmt, ap);
va_end(ap);
exit(eval);
}
void
errx(int eval, const char *fmt, ...)
{
va_list ap;
va_start(ap, fmt);
vwarnxi(fmt, ap);
va_end(ap);
fputc('\n', stderr);
exit(eval);
}
void
warn(const char *fmt, ...)
{
va_list ap;
va_start(ap, fmt);
vwarni(fmt, ap);
va_end(ap);
}
void
warnx(const char *fmt, ...)
{
va_list ap;
va_start(ap, fmt);
vwarnxi(fmt, ap);
va_end(ap);
fputc('\n', stderr);
}
#endif
mandoc-1.14.3/compat_fts.c 0100644 0002007 0000011 00000042654 13141336266 0014774 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_FTS
int dummy;
#else
/* $Id: compat_fts.c,v 1.14 2017/02/18 12:24:24 schwarze Exp $ */
/* $OpenBSD: fts.c,v 1.56 2016/09/21 04:38:56 guenther Exp $ */
/*-
* Copyright (c) 1990, 1993, 1994
* The Regents of the University of California. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the University nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*/
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include "compat_fts.h"
#define MAXIMUM(a, b) (((a) > (b)) ? (a) : (b))
static FTSENT *fts_alloc(FTS *, const char *, size_t);
static FTSENT *fts_build(FTS *);
static void fts_lfree(FTSENT *);
static void fts_load(FTS *, FTSENT *);
static size_t fts_maxarglen(char * const *);
static void fts_padjust(FTS *, FTSENT *);
static int fts_palloc(FTS *, size_t);
static FTSENT *fts_sort(FTS *, FTSENT *, int);
static unsigned short fts_stat(FTS *, FTSENT *);
#define ISDOT(a) (a[0] == '.' && (!a[1] || (a[1] == '.' && !a[2])))
#ifndef O_CLOEXEC
#define O_CLOEXEC 0
#endif
#define CLR(opt) (sp->fts_options &= ~(opt))
#define ISSET(opt) (sp->fts_options & (opt))
#define SET(opt) (sp->fts_options |= (opt))
FTS *
fts_open(char * const *argv, int options,
int (*compar)(const FTSENT **, const FTSENT **))
{
FTS *sp;
FTSENT *p, *root;
int nitems;
FTSENT *parent, *prev;
/* Options check. */
if (options & ~FTS_OPTIONMASK) {
errno = EINVAL;
return (NULL);
}
/* At least one path must be specified. */
if (*argv == NULL) {
errno = EINVAL;
return (NULL);
}
/* Allocate/initialize the stream */
if ((sp = calloc(1, sizeof(FTS))) == NULL)
return (NULL);
sp->fts_compar = compar;
sp->fts_options = options;
/*
* Start out with 1K of path space, and enough, in any case,
* to hold the user's paths.
*/
if (fts_palloc(sp, MAXIMUM(fts_maxarglen(argv), PATH_MAX)))
goto mem1;
/* Allocate/initialize root's parent. */
if ((parent = fts_alloc(sp, "", 0)) == NULL)
goto mem2;
parent->fts_level = FTS_ROOTPARENTLEVEL;
/* Allocate/initialize root(s). */
for (root = prev = NULL, nitems = 0; *argv; ++argv, ++nitems) {
if ((p = fts_alloc(sp, *argv, strlen(*argv))) == NULL)
goto mem3;
p->fts_level = FTS_ROOTLEVEL;
p->fts_parent = parent;
p->fts_accpath = p->fts_name;
p->fts_info = fts_stat(sp, p);
/* Command-line "." and ".." are real directories. */
if (p->fts_info == FTS_DOT)
p->fts_info = FTS_D;
/*
* If comparison routine supplied, traverse in sorted
* order; otherwise traverse in the order specified.
*/
if (compar) {
p->fts_link = root;
root = p;
} else {
p->fts_link = NULL;
if (root == NULL)
root = p;
else
prev->fts_link = p;
prev = p;
}
}
if (compar && nitems > 1)
root = fts_sort(sp, root, nitems);
/*
* Allocate a dummy pointer and make fts_read think that we've just
* finished the node before the root(s); set p->fts_info to FTS_INIT
* so that everything about the "current" node is ignored.
*/
if ((sp->fts_cur = fts_alloc(sp, "", 0)) == NULL)
goto mem3;
sp->fts_cur->fts_link = root;
sp->fts_cur->fts_info = FTS_INIT;
if (nitems == 0)
free(parent);
return (sp);
mem3: fts_lfree(root);
free(parent);
mem2: free(sp->fts_path);
mem1: free(sp);
return (NULL);
}
static void
fts_load(FTS *sp, FTSENT *p)
{
size_t len;
char *cp;
/*
* Load the stream structure for the next traversal. Since we don't
* actually enter the directory until after the preorder visit, set
* the fts_accpath field specially so the chdir gets done to the right
* place and the user can access the first node. From fts_open it's
* known that the path will fit.
*/
len = p->fts_pathlen = p->fts_namelen;
memmove(sp->fts_path, p->fts_name, len + 1);
if ((cp = strrchr(p->fts_name, '/')) && (cp != p->fts_name || cp[1])) {
len = strlen(++cp);
memmove(p->fts_name, cp, len + 1);
p->fts_namelen = len;
}
p->fts_accpath = p->fts_path = sp->fts_path;
sp->fts_dev = p->fts_dev;
}
int
fts_close(FTS *sp)
{
FTSENT *freep, *p;
/*
* This still works if we haven't read anything -- the dummy structure
* points to the root list, so we step through to the end of the root
* list which has a valid parent pointer.
*/
if (sp->fts_cur) {
for (p = sp->fts_cur; p->fts_level >= FTS_ROOTLEVEL;) {
freep = p;
p = p->fts_link ? p->fts_link : p->fts_parent;
free(freep);
}
free(p);
}
/* Free up child linked list, sort array, path buffer, stream ptr.*/
if (sp->fts_child)
fts_lfree(sp->fts_child);
free(sp->fts_array);
free(sp->fts_path);
free(sp);
return (0);
}
/*
* Special case of "/" at the end of the path so that slashes aren't
* appended which would cause paths to be written as "....//foo".
*/
#define NAPPEND(p) \
(p->fts_path[p->fts_pathlen - 1] == '/' \
? p->fts_pathlen - 1 : p->fts_pathlen)
FTSENT *
fts_read(FTS *sp)
{
FTSENT *p, *tmp;
int instr;
char *t;
/* If finished or unrecoverable error, return NULL. */
if (sp->fts_cur == NULL || ISSET(FTS_STOP))
return (NULL);
/* Set current node pointer. */
p = sp->fts_cur;
/* Save and zero out user instructions. */
instr = p->fts_instr;
p->fts_instr = FTS_NOINSTR;
/* Directory in pre-order. */
if (p->fts_info == FTS_D) {
/* If skipped or crossed mount point, do post-order visit. */
if (instr == FTS_SKIP ||
(ISSET(FTS_XDEV) && p->fts_dev != sp->fts_dev)) {
if (sp->fts_child) {
fts_lfree(sp->fts_child);
sp->fts_child = NULL;
}
p->fts_info = FTS_DP;
return (p);
}
/*
* If haven't read do so. If the read fails, fts_build sets
* FTS_STOP or the fts_info field of the node.
*/
if (sp->fts_child) {
/* nothing */
} else if ((sp->fts_child = fts_build(sp)) == NULL) {
if (ISSET(FTS_STOP))
return (NULL);
return (p);
}
p = sp->fts_child;
sp->fts_child = NULL;
goto name;
}
/* Move to the next node on this level. */
next: tmp = p;
if ((p = p->fts_link)) {
free(tmp);
/*
* If reached the top, return to the original directory (or
* the root of the tree), and load the paths for the next root.
*/
if (p->fts_level == FTS_ROOTLEVEL) {
fts_load(sp, p);
return (sp->fts_cur = p);
}
/*
* User may have called fts_set on the node. If skipped,
* ignore. If followed, get a file descriptor so we can
* get back if necessary.
*/
if (p->fts_instr == FTS_SKIP)
goto next;
name: t = sp->fts_path + NAPPEND(p->fts_parent);
*t++ = '/';
memmove(t, p->fts_name, p->fts_namelen + 1);
return (sp->fts_cur = p);
}
/* Move up to the parent node. */
p = tmp->fts_parent;
free(tmp);
if (p->fts_level == FTS_ROOTPARENTLEVEL) {
/*
* Done; free everything up and set errno to 0 so the user
* can distinguish between error and EOF.
*/
free(p);
errno = 0;
return (sp->fts_cur = NULL);
}
/* NUL terminate the pathname. */
sp->fts_path[p->fts_pathlen] = '\0';
p->fts_info = p->fts_errno ? FTS_ERR : FTS_DP;
return (sp->fts_cur = p);
}
/*
* Fts_set takes the stream as an argument although it's not used in this
* implementation; it would be necessary if anyone wanted to add global
* semantics to fts using fts_set. An error return is allowed for similar
* reasons.
*/
int
fts_set(FTS *sp, FTSENT *p, int instr)
{
if (instr && instr != FTS_NOINSTR && instr != FTS_SKIP) {
errno = EINVAL;
return (1);
}
p->fts_instr = instr;
return (0);
}
/*
* This is the tricky part -- do not casually change *anything* in here. The
* idea is to build the linked list of entries that are used by fts_children
* and fts_read. There are lots of special cases.
*
* The real slowdown in walking the tree is the stat calls. If FTS_NOSTAT is
* set and it's a physical walk (so that symbolic links can't be directories),
* we can do things quickly. First, if it's a 4.4BSD file system, the type
* of the file is in the directory entry. Otherwise, we assume that the number
* of subdirectories in a node is equal to the number of links to the parent.
* The former skips all stat calls. The latter skips stat calls in any leaf
* directories and for any files after the subdirectories in the directory have
* been found, cutting the stat calls by about 2/3.
*/
static FTSENT *
fts_build(FTS *sp)
{
struct dirent *dp;
FTSENT *p, *head;
FTSENT *cur, *tail;
DIR *dirp;
void *oldaddr;
size_t dlen, len, maxlen;
int nitems, level, doadjust;
int saved_errno;
char *cp;
/* Set current node pointer. */
cur = sp->fts_cur;
/*
* Open the directory for reading. If this fails, we're done.
* If being called from fts_read, set the fts_info field.
*/
if ((dirp = opendir(cur->fts_accpath)) == NULL) {
cur->fts_info = FTS_DNR;
cur->fts_errno = errno;
return (NULL);
}
/*
* Figure out the max file name length that can be stored in the
* current path -- the inner loop allocates more path as necessary.
* We really wouldn't have to do the maxlen calculations here, we
* could do them in fts_read before returning the path, but it's a
* lot easier here since the length is part of the dirent structure.
*
* If not changing directories set a pointer so that can just append
* each new name into the path.
*/
len = NAPPEND(cur);
cp = sp->fts_path + len;
*cp++ = '/';
len++;
maxlen = sp->fts_pathlen - len;
/*
* fts_level is signed so we must prevent it from wrapping
* around to FTS_ROOTLEVEL and FTS_ROOTPARENTLEVEL.
*/
level = cur->fts_level;
if (level < FTS_MAXLEVEL)
level++;
/* Read the directory, attaching each entry to the `link' pointer. */
doadjust = 0;
for (head = tail = NULL, nitems = 0; dirp && (dp = readdir(dirp));) {
if (ISDOT(dp->d_name))
continue;
#if HAVE_DIRENT_NAMLEN
dlen = dp->d_namlen;
#else
dlen = strlen(dp->d_name);
#endif
if (!(p = fts_alloc(sp, dp->d_name, dlen)))
goto mem1;
if (dlen >= maxlen) { /* include space for NUL */
oldaddr = sp->fts_path;
if (fts_palloc(sp, dlen + len + 1)) {
/*
* No more memory for path or structures. Save
* errno, free up the current structure and the
* structures already allocated.
*/
mem1: saved_errno = errno;
free(p);
fts_lfree(head);
(void)closedir(dirp);
cur->fts_info = FTS_ERR;
SET(FTS_STOP);
errno = saved_errno;
return (NULL);
}
/* Did realloc() change the pointer? */
if (oldaddr != sp->fts_path) {
doadjust = 1;
cp = sp->fts_path + len;
}
maxlen = sp->fts_pathlen - len;
}
p->fts_level = level;
p->fts_parent = sp->fts_cur;
p->fts_pathlen = len + dlen;
if (p->fts_pathlen < len) {
/*
* If we wrap, free up the current structure and
* the structures already allocated, then error
* out with ENAMETOOLONG.
*/
free(p);
fts_lfree(head);
(void)closedir(dirp);
cur->fts_info = FTS_ERR;
SET(FTS_STOP);
errno = ENAMETOOLONG;
return (NULL);
}
/* Build a file name for fts_stat to stat. */
p->fts_accpath = p->fts_path;
memmove(cp, p->fts_name, p->fts_namelen + 1);
/* Stat it. */
p->fts_info = fts_stat(sp, p);
/* We walk in directory order so "ls -f" doesn't get upset. */
p->fts_link = NULL;
if (head == NULL)
head = tail = p;
else {
tail->fts_link = p;
tail = p;
}
++nitems;
}
if (dirp)
(void)closedir(dirp);
/*
* If realloc() changed the address of the path, adjust the
* addresses for the rest of the tree and the dir list.
*/
if (doadjust)
fts_padjust(sp, head);
/*
* If not changing directories, reset the path back to original
* state.
*/
if (len == sp->fts_pathlen || nitems == 0)
--cp;
*cp = '\0';
/* If didn't find anything, return NULL. */
if (!nitems) {
cur->fts_info = FTS_DP;
return (NULL);
}
/* Sort the entries. */
if (sp->fts_compar && nitems > 1)
head = fts_sort(sp, head, nitems);
return (head);
}
static unsigned short
fts_stat(FTS *sp, FTSENT *p)
{
FTSENT *t;
dev_t dev;
ino_t ino;
struct stat *sbp;
/* If user needs stat info, stat buffer already allocated. */
sbp = p->fts_statp;
if (lstat(p->fts_accpath, sbp)) {
p->fts_errno = errno;
memset(sbp, 0, sizeof(struct stat));
return (FTS_NS);
}
if (S_ISDIR(sbp->st_mode)) {
/*
* Set the device/inode. Used to find cycles and check for
* crossing mount points. Also remember the link count, used
* in fts_build to limit the number of stat calls. It is
* understood that these fields are only referenced if fts_info
* is set to FTS_D.
*/
dev = p->fts_dev = sbp->st_dev;
ino = p->fts_ino = sbp->st_ino;
p->fts_nlink = sbp->st_nlink;
if (ISDOT(p->fts_name))
return (FTS_DOT);
/*
* Cycle detection is done by brute force when the directory
* is first encountered. If the tree gets deep enough or the
* number of symbolic links to directories is high enough,
* something faster might be worthwhile.
*/
for (t = p->fts_parent;
t->fts_level >= FTS_ROOTLEVEL; t = t->fts_parent)
if (ino == t->fts_ino && dev == t->fts_dev) {
p->fts_cycle = t;
return (FTS_DC);
}
return (FTS_D);
}
if (S_ISLNK(sbp->st_mode))
return (FTS_SL);
if (S_ISREG(sbp->st_mode))
return (FTS_F);
return (FTS_DEFAULT);
}
static FTSENT *
fts_sort(FTS *sp, FTSENT *head, int nitems)
{
FTSENT **ap, *p;
/*
* Construct an array of pointers to the structures and call qsort(3).
* Reassemble the array in the order returned by qsort. If unable to
* sort for memory reasons, return the directory entries in their
* current order. Allocate enough space for the current needs plus
* 40 so don't realloc one entry at a time.
*/
if (nitems > sp->fts_nitems) {
struct _ftsent **a;
sp->fts_nitems = nitems + 40;
if ((a = reallocarray(sp->fts_array,
sp->fts_nitems, sizeof(FTSENT *))) == NULL) {
free(sp->fts_array);
sp->fts_array = NULL;
sp->fts_nitems = 0;
return (head);
}
sp->fts_array = a;
}
for (ap = sp->fts_array, p = head; p; p = p->fts_link)
*ap++ = p;
qsort(sp->fts_array, nitems, sizeof(FTSENT *), sp->fts_compar);
for (head = *(ap = sp->fts_array); --nitems; ++ap)
ap[0]->fts_link = ap[1];
ap[0]->fts_link = NULL;
return (head);
}
static FTSENT *
fts_alloc(FTS *sp, const char *name, size_t namelen)
{
FTSENT *p;
size_t len;
len = sizeof(FTSENT) + namelen;
if ((p = calloc(1, len)) == NULL)
return (NULL);
p->fts_path = sp->fts_path;
p->fts_namelen = namelen;
p->fts_instr = FTS_NOINSTR;
p->fts_statp = malloc(sizeof(struct stat));
if (p->fts_statp == NULL) {
free(p);
return (NULL);
}
memcpy(p->fts_name, name, namelen);
return (p);
}
static void
fts_lfree(FTSENT *head)
{
FTSENT *p;
/* Free a linked list of structures. */
while ((p = head)) {
head = head->fts_link;
free(p);
}
}
/*
* Allow essentially unlimited paths; find, rm, ls should all work on any tree.
* Most systems will allow creation of paths much longer than PATH_MAX, even
* though the kernel won't resolve them. Add the size (not just what's needed)
* plus 256 bytes so don't realloc the path 2 bytes at a time.
*/
static int
fts_palloc(FTS *sp, size_t more)
{
char *p;
/*
* Check for possible wraparound.
*/
more += 256;
if (sp->fts_pathlen + more < sp->fts_pathlen) {
free(sp->fts_path);
sp->fts_path = NULL;
errno = ENAMETOOLONG;
return (1);
}
sp->fts_pathlen += more;
p = realloc(sp->fts_path, sp->fts_pathlen);
if (p == NULL) {
free(sp->fts_path);
sp->fts_path = NULL;
return (1);
}
sp->fts_path = p;
return (0);
}
/*
* When the path is realloc'd, have to fix all of the pointers in structures
* already returned.
*/
static void
fts_padjust(FTS *sp, FTSENT *head)
{
FTSENT *p;
char *addr = sp->fts_path;
#define ADJUST(p) { \
if ((p)->fts_accpath != (p)->fts_name) { \
(p)->fts_accpath = \
(char *)addr + ((p)->fts_accpath - (p)->fts_path); \
} \
(p)->fts_path = addr; \
}
/* Adjust the current set of children. */
for (p = sp->fts_child; p; p = p->fts_link)
ADJUST(p);
/* Adjust the rest of the tree, including the current level. */
for (p = head; p->fts_level >= FTS_ROOTLEVEL;) {
ADJUST(p);
p = p->fts_link ? p->fts_link : p->fts_parent;
}
}
static size_t
fts_maxarglen(char * const *argv)
{
size_t len, max;
for (max = 0; *argv; ++argv)
if ((len = strlen(*argv)) > max)
max = len;
return (max + 1);
}
#endif
mandoc-1.14.3/compat_ohash.c 0100644 0002007 0000011 00000015507 13141336266 0015277 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_OHASH
int dummy;
#else
/* $OpenBSD: ohash.c,v 1.1 2014/06/02 18:52:03 deraadt Exp $ */
/* Copyright (c) 1999, 2004 Marc Espie
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#include
#include
#include
#include
#include
#include
#include "compat_ohash.h"
struct _ohash_record {
uint32_t hv;
const char *p;
};
#define DELETED ((const char *)h)
#define NONE (h->size)
/* Don't bother changing the hash table if the change is small enough. */
#define MINSIZE (1UL << 4)
#define MINDELETED 4
static void ohash_resize(struct ohash *);
/* This handles the common case of variable length keys, where the
* key is stored at the end of the record.
*/
void *
ohash_create_entry(struct ohash_info *i, const char *start, const char **end)
{
char *p;
if (!*end)
*end = start + strlen(start);
p = (i->alloc)(i->key_offset + (*end - start) + 1, i->data);
if (p) {
memcpy(p+i->key_offset, start, *end-start);
p[i->key_offset + (*end - start)] = '\0';
}
return (void *)p;
}
/* hash_delete only frees the hash structure. Use hash_first/hash_next
* to free entries as well. */
void
ohash_delete(struct ohash *h)
{
(h->info.free)(h->t, h->info.data);
#ifndef NDEBUG
h->t = NULL;
#endif
}
static void
ohash_resize(struct ohash *h)
{
struct _ohash_record *n;
size_t ns;
unsigned int j;
unsigned int i, incr;
if (4 * h->deleted < h->total) {
if (h->size >= (UINT_MAX >> 1U))
ns = UINT_MAX;
else
ns = h->size << 1U;
} else if (3 * h->deleted > 2 * h->total)
ns = h->size >> 1U;
else
ns = h->size;
if (ns < MINSIZE)
ns = MINSIZE;
#ifdef STATS_HASH
STAT_HASH_EXPAND++;
STAT_HASH_SIZE += ns - h->size;
#endif
n = (h->info.calloc)(ns, sizeof(struct _ohash_record), h->info.data);
if (!n)
return;
for (j = 0; j < h->size; j++) {
if (h->t[j].p != NULL && h->t[j].p != DELETED) {
i = h->t[j].hv % ns;
incr = ((h->t[j].hv % (ns - 2)) & ~1) + 1;
while (n[i].p != NULL) {
i += incr;
if (i >= ns)
i -= ns;
}
n[i].hv = h->t[j].hv;
n[i].p = h->t[j].p;
}
}
(h->info.free)(h->t, h->info.data);
h->t = n;
h->size = ns;
h->total -= h->deleted;
h->deleted = 0;
}
void *
ohash_remove(struct ohash *h, unsigned int i)
{
void *result = (void *)h->t[i].p;
if (result == NULL || result == DELETED)
return NULL;
#ifdef STATS_HASH
STAT_HASH_ENTRIES--;
#endif
h->t[i].p = DELETED;
h->deleted++;
if (h->deleted >= MINDELETED && 4 * h->deleted > h->total)
ohash_resize(h);
return result;
}
void *
ohash_find(struct ohash *h, unsigned int i)
{
if (h->t[i].p == DELETED)
return NULL;
else
return (void *)h->t[i].p;
}
void *
ohash_insert(struct ohash *h, unsigned int i, void *p)
{
#ifdef STATS_HASH
STAT_HASH_ENTRIES++;
#endif
if (h->t[i].p == DELETED) {
h->deleted--;
h->t[i].p = p;
} else {
h->t[i].p = p;
/* Arbitrary resize boundary. Tweak if not efficient enough. */
if (++h->total * 4 > h->size * 3)
ohash_resize(h);
}
return p;
}
unsigned int
ohash_entries(struct ohash *h)
{
return h->total - h->deleted;
}
void *
ohash_first(struct ohash *h, unsigned int *pos)
{
*pos = 0;
return ohash_next(h, pos);
}
void *
ohash_next(struct ohash *h, unsigned int *pos)
{
for (; *pos < h->size; (*pos)++)
if (h->t[*pos].p != DELETED && h->t[*pos].p != NULL)
return (void *)h->t[(*pos)++].p;
return NULL;
}
void
ohash_init(struct ohash *h, unsigned int size, struct ohash_info *info)
{
h->size = 1UL << size;
if (h->size < MINSIZE)
h->size = MINSIZE;
#ifdef STATS_HASH
STAT_HASH_CREATION++;
STAT_HASH_SIZE += h->size;
#endif
/* Copy info so that caller may free it. */
h->info.key_offset = info->key_offset;
h->info.calloc = info->calloc;
h->info.free = info->free;
h->info.alloc = info->alloc;
h->info.data = info->data;
h->t = (h->info.calloc)(h->size, sizeof(struct _ohash_record),
h->info.data);
h->total = h->deleted = 0;
}
uint32_t
ohash_interval(const char *s, const char **e)
{
uint32_t k;
if (!*e)
*e = s + strlen(s);
if (s == *e)
k = 0;
else
k = *s++;
while (s != *e)
k = ((k << 2) | (k >> 30)) ^ *s++;
return k;
}
unsigned int
ohash_lookup_interval(struct ohash *h, const char *start, const char *end,
uint32_t hv)
{
unsigned int i, incr;
unsigned int empty;
#ifdef STATS_HASH
STAT_HASH_LOOKUP++;
#endif
empty = NONE;
i = hv % h->size;
incr = ((hv % (h->size-2)) & ~1) + 1;
while (h->t[i].p != NULL) {
#ifdef STATS_HASH
STAT_HASH_LENGTH++;
#endif
if (h->t[i].p == DELETED) {
if (empty == NONE)
empty = i;
} else if (h->t[i].hv == hv &&
strncmp(h->t[i].p+h->info.key_offset, start,
end - start) == 0 &&
(h->t[i].p+h->info.key_offset)[end-start] == '\0') {
if (empty != NONE) {
h->t[empty].hv = hv;
h->t[empty].p = h->t[i].p;
h->t[i].p = DELETED;
return empty;
} else {
#ifdef STATS_HASH
STAT_HASH_POSITIVE++;
#endif
return i;
}
}
i += incr;
if (i >= h->size)
i -= h->size;
}
/* Found an empty position. */
if (empty != NONE)
i = empty;
h->t[i].hv = hv;
return i;
}
unsigned int
ohash_lookup_memory(struct ohash *h, const char *k, size_t size, uint32_t hv)
{
unsigned int i, incr;
unsigned int empty;
#ifdef STATS_HASH
STAT_HASH_LOOKUP++;
#endif
empty = NONE;
i = hv % h->size;
incr = ((hv % (h->size-2)) & ~1) + 1;
while (h->t[i].p != NULL) {
#ifdef STATS_HASH
STAT_HASH_LENGTH++;
#endif
if (h->t[i].p == DELETED) {
if (empty == NONE)
empty = i;
} else if (h->t[i].hv == hv &&
memcmp(h->t[i].p+h->info.key_offset, k, size) == 0) {
if (empty != NONE) {
h->t[empty].hv = hv;
h->t[empty].p = h->t[i].p;
h->t[i].p = DELETED;
return empty;
} else {
#ifdef STATS_HASH
STAT_HASH_POSITIVE++;
#endif
} return i;
}
i += incr;
if (i >= h->size)
i -= h->size;
}
/* Found an empty position. */
if (empty != NONE)
i = empty;
h->t[i].hv = hv;
return i;
}
unsigned int
ohash_qlookup(struct ohash *h, const char *s)
{
const char *e = NULL;
return ohash_qlookupi(h, s, &e);
}
unsigned int
ohash_qlookupi(struct ohash *h, const char *s, const char **e)
{
uint32_t hv;
hv = ohash_interval(s, e);
return ohash_lookup_interval(h, s, *e, hv);
}
#endif /*!HAVE_OHASH*/
mandoc-1.14.3/compat_getline.c 0100644 0002007 0000011 00000003130 13141336266 0015611 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_GETLINE
int dummy;
#else
/* $Id: compat_getline.c,v 1.1 2015/11/07 20:52:52 schwarze Exp $ */
/*
* Copyright (c) 2015 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#include
#include
#include
#include
ssize_t
getline(char **buf, size_t *bufsz, FILE *fp)
{
char *nbuf;
size_t nbufsz, pos;
int c;
if (buf == NULL || bufsz == NULL) {
errno = EINVAL;
return -1;
}
if (*buf == NULL)
*bufsz = 0;
else
**buf = '\0';
pos = 0;
for (;;) {
if (pos + 1 >= *bufsz) {
nbufsz = *bufsz ? *bufsz * 2 : BUFSIZ;
if ((nbuf = realloc(*buf, nbufsz)) == NULL)
return -1;
*buf = nbuf;
*bufsz = nbufsz;
}
if ((c = fgetc(fp)) == EOF) {
(*buf)[pos] = '\0';
return pos > 0 && feof(fp) ? (ssize_t)pos : -1;
}
(*buf)[pos++] = c;
(*buf)[pos] = '\0';
if (c == '\n')
return pos;
}
}
#endif
mandoc-1.14.3/compat_getsubopt.c 0100644 0002007 0000011 00000005615 13141336266 0016210 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_GETSUBOPT
int dummy;
#else
/* $Id: compat_getsubopt.c,v 1.5 2014/08/17 20:53:50 schwarze Exp $ */
/* $OpenBSD: getsubopt.c,v 1.4 2005/08/08 08:05:36 espie Exp $ */
/*-
* Copyright (c) 1990, 1993
* The Regents of the University of California. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the University nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*/
#include
#include
#include
int
getsubopt(char **optionp, char * const *tokens, char **valuep)
{
int cnt;
char *suboptarg;
char *p;
suboptarg = *valuep = NULL;
if (!optionp || !*optionp)
return(-1);
/* skip leading white-space, commas */
for (p = *optionp; *p && (*p == ',' || *p == ' ' || *p == '\t'); ++p);
if (!*p) {
*optionp = p;
return(-1);
}
/* save the start of the token, and skip the rest of the token. */
for (suboptarg = p;
*++p && *p != ',' && *p != '=' && *p != ' ' && *p != '\t';);
if (*p) {
/*
* If there's an equals sign, set the value pointer, and
* skip over the value part of the token. Terminate the
* token.
*/
if (*p == '=') {
*p = '\0';
for (*valuep = ++p;
*p && *p != ',' && *p != ' ' && *p != '\t'; ++p);
if (*p)
*p++ = '\0';
} else
*p++ = '\0';
/* Skip any whitespace or commas after this token. */
for (; *p && (*p == ',' || *p == ' ' || *p == '\t'); ++p);
}
/* set optionp for next round. */
*optionp = p;
for (cnt = 0; *tokens; ++tokens, ++cnt)
if (!strcmp(suboptarg, *tokens))
return(cnt);
return(-1);
}
#endif
mandoc-1.14.3/compat_isblank.c 0100644 0002007 0000011 00000001732 13141336266 0015613 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_ISBLANK
int dummy;
#else
/* $Id: compat_isblank.c,v 1.2 2015/10/06 18:32:19 schwarze Exp $ */
/*
* Copyright (c) 2015 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
int
isblank(int c)
{
return c == ' ' || c == '\t';
}
#endif
mandoc-1.14.3/compat_mkdtemp.c 0100644 0002007 0000011 00000003130 13141336266 0015623 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_MKDTEMP
int dummy;
#else
/* $Id: compat_mkdtemp.c,v 1.2 2015/10/06 18:32:19 schwarze Exp $ */
/*
* Copyright (c) 2015 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*
* The algorithm of this function is inspired by OpenBSD mkdtemp(3)
* by Theo de Raadt and Todd Miller, but the code differs.
*/
#include
#include
#include
#include
#include
char *
mkdtemp(char *path)
{
char *start, *cp;
unsigned int tries;
start = strchr(path, '\0');
while (start > path && start[-1] == 'X')
start--;
for (tries = INT_MAX; tries; tries--) {
if (mktemp(path) == NULL) {
errno = EEXIST;
return NULL;
}
if (mkdir(path, S_IRUSR | S_IWUSR | S_IXUSR) == 0)
return path;
if (errno != EEXIST)
return NULL;
for (cp = start; *cp != '\0'; cp++)
*cp = 'X';
}
errno = EEXIST;
return NULL;
}
#endif
mandoc-1.14.3/compat_progname.c 0100644 0002007 0000011 00000002064 13141336266 0015777 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_PROGNAME
int dummy;
#else
/* $Id: compat_progname.c,v 1.1 2015/11/06 16:30:33 schwarze Exp $ */
/*
* Copyright (c) 2015 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
static const char *progname;
void
setprogname(const char *name)
{
progname = name;
}
const char *
getprogname(void)
{
return progname;
}
#endif
mandoc-1.14.3/compat_reallocarray.c 0100644 0002007 0000011 00000002770 13141336266 0016653 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_REALLOCARRAY
int dummy;
#else
/* $Id: compat_reallocarray.c,v 1.4 2014/12/11 09:05:01 schwarze Exp $ */
/* $OpenBSD: reallocarray.c,v 1.2 2014/12/08 03:45:00 bcook Exp $ */
/*
* Copyright (c) 2008 Otto Moerbeek
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#include
#include
#include
#include
/*
* This is sqrt(SIZE_MAX+1), as s1*s2 <= SIZE_MAX
* if both s1 < MUL_NO_OVERFLOW and s2 < MUL_NO_OVERFLOW
*/
#define MUL_NO_OVERFLOW ((size_t)1 << (sizeof(size_t) * 4))
void *
reallocarray(void *optr, size_t nmemb, size_t size)
{
if ((nmemb >= MUL_NO_OVERFLOW || size >= MUL_NO_OVERFLOW) &&
nmemb > 0 && SIZE_MAX / nmemb < size) {
errno = ENOMEM;
return NULL;
}
return realloc(optr, size * nmemb);
}
#endif /*!HAVE_REALLOCARRAY*/
mandoc-1.14.3/compat_recallocarray.c 0100644 0002007 0000011 00000005611 13141336266 0017013 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_RECALLOCARRAY
int dummy;
#else
/* $Id: compat_recallocarray.c,v 1.1 2017/06/12 19:05:47 schwarze Exp $ */
/* $OpenBSD: malloc.c,v 1.225 2017/05/13 07:11:29 otto Exp $ */
/*
* Copyright (c) 2017 Otto Moerbeek
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#include
#include
#include
#include
#include
/*
* This is sqrt(SIZE_MAX+1), as s1*s2 <= SIZE_MAX
* if both s1 < MUL_NO_OVERFLOW and s2 < MUL_NO_OVERFLOW
*/
#define MUL_NO_OVERFLOW ((size_t)1 << (sizeof(size_t) * 4))
/*
* Even though specified in POSIX, the PAGESIZE and PAGE_SIZE
* macros have very poor portability. Since we only use this
* to avoid free() overhead for small shrinking, simply pick
* an arbitrary number.
*/
#define MALLOC_PAGESIZE (1UL << 12)
void *
recallocarray(void *ptr, size_t oldnmemb, size_t newnmemb, size_t size)
{
size_t oldsize, newsize;
void *newptr;
if (ptr == NULL)
return calloc(newnmemb, size);
if ((newnmemb >= MUL_NO_OVERFLOW || size >= MUL_NO_OVERFLOW) &&
newnmemb > 0 && SIZE_MAX / newnmemb < size) {
errno = ENOMEM;
return NULL;
}
newsize = newnmemb * size;
if ((oldnmemb >= MUL_NO_OVERFLOW || size >= MUL_NO_OVERFLOW) &&
oldnmemb > 0 && SIZE_MAX / oldnmemb < size) {
errno = EINVAL;
return NULL;
}
oldsize = oldnmemb * size;
/*
* Don't bother too much if we're shrinking just a bit,
* we do not shrink for series of small steps, oh well.
*/
if (newsize <= oldsize) {
size_t d = oldsize - newsize;
if (d < oldsize / 2 && d < MALLOC_PAGESIZE) {
memset((char *)ptr + newsize, 0, d);
return ptr;
}
}
newptr = malloc(newsize);
if (newptr == NULL)
return NULL;
if (newsize > oldsize) {
memcpy(newptr, ptr, oldsize);
memset((char *)newptr + oldsize, 0, newsize - oldsize);
} else
memcpy(newptr, ptr, newsize);
/*
* At this point, the OpenBSD implementation calls
* explicit_bzero() on the old memory before it is
* freed. Since explicit_bzero() is hard to implement
* portably and we don't handle confidential data in
* mandoc in the first place, simply free the memory
* without clearing it.
*/
free(ptr);
return newptr;
}
#endif /* !HAVE_RECALLOCARRAY */
mandoc-1.14.3/compat_strcasestr.c 0100644 0002007 0000011 00000004603 13141336266 0016365 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_STRCASESTR
int dummy;
#else
/* $Id: compat_strcasestr.c,v 1.4 2014/12/11 09:19:32 schwarze Exp $ */
/* $NetBSD: strcasestr.c,v 1.3 2005/11/29 03:12:00 christos Exp $ */
/*-
* Copyright (c) 1990, 1993
* The Regents of the University of California. All rights reserved.
*
* This code is derived from software contributed to Berkeley by
* Chris Torek.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the University nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*/
#include
#include
#include
#define __UNCONST(a) ((void *)(unsigned long)(const void *)(a))
/*
* Find the first occurrence of find in s, ignore case.
*/
char *
strcasestr(const char *s, const char *find)
{
char c, sc;
size_t len;
if ((c = *find++) != 0) {
c = tolower((unsigned char)c);
len = strlen(find);
do {
do {
if ((sc = *s++) == 0)
return (NULL);
} while ((char)tolower((unsigned char)sc) != c);
} while (strncasecmp(s, find, len) != 0);
s--;
}
return __UNCONST(s);
}
#endif
mandoc-1.14.3/compat_stringlist.c 0100644 0002007 0000011 00000005325 13141336266 0016374 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_STRINGLIST
int dummy;
#else
/* $Id: compat_stringlist.c,v 1.6 2015/11/07 14:22:29 schwarze Exp $ */
/*
* Copyright (c) 1994 Christos Zoulas
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
* OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
* DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*/
#if HAVE_ERR
#include
#endif
#include
#include
#include "compat_stringlist.h"
#define _SL_CHUNKSIZE 20
/*
* sl_init(): Initialize a string list
*/
StringList *
sl_init(void)
{
StringList *sl;
sl = malloc(sizeof(StringList));
if (sl == NULL)
err(1, "stringlist");
sl->sl_cur = 0;
sl->sl_max = _SL_CHUNKSIZE;
sl->sl_str = reallocarray(NULL, sl->sl_max, sizeof(char *));
if (sl->sl_str == NULL)
err(1, "stringlist");
return sl;
}
/*
* sl_add(): Add an item to the string list
*/
int
sl_add(StringList *sl, char *name)
{
if (sl->sl_cur == sl->sl_max - 1) {
sl->sl_max += _SL_CHUNKSIZE;
sl->sl_str = reallocarray(sl->sl_str,
sl->sl_max, sizeof(char *));
if (sl->sl_str == NULL)
return (-1);
}
sl->sl_str[sl->sl_cur++] = name;
return (0);
}
/*
* sl_free(): Free a stringlist
*/
void
sl_free(StringList *sl, int all)
{
size_t i;
if (sl == NULL)
return;
if (sl->sl_str) {
if (all)
for (i = 0; i < sl->sl_cur; i++)
free(sl->sl_str[i]);
free(sl->sl_str);
}
free(sl);
}
/*
* sl_find(): Find a name in the string list
*/
char *
sl_find(StringList *sl, const char *name)
{
size_t i;
for (i = 0; i < sl->sl_cur; i++)
if (strcmp(sl->sl_str[i], name) == 0)
return sl->sl_str[i];
return NULL;
}
#endif
mandoc-1.14.3/compat_strlcat.c 0100644 0002007 0000011 00000003325 13141336266 0015644 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_STRLCAT
int dummy;
#else
/* $OpenBSD: strlcat.c,v 1.13 2005/08/08 08:05:37 espie Exp $ */
/*
* Copyright (c) 1998 Todd C. Miller
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#include
#include
/*
* Appends src to string dst of size siz (unlike strncat, siz is the
* full size of dst, not space left). At most siz-1 characters
* will be copied. Always NUL terminates (unless siz <= strlen(dst)).
* Returns strlen(src) + MIN(siz, strlen(initial dst)).
* If retval >= siz, truncation occurred.
*/
size_t
strlcat(char *dst, const char *src, size_t siz)
{
char *d = dst;
const char *s = src;
size_t n = siz;
size_t dlen;
/* Find the end of dst and adjust bytes left but don't go past end */
while (n-- != 0 && *d != '\0')
d++;
dlen = d - dst;
n = siz - dlen;
if (n == 0)
return(dlen + strlen(s));
while (*s != '\0') {
if (n != 1) {
*d++ = *s;
n--;
}
s++;
}
*d = '\0';
return(dlen + (s - src)); /* count does not include NUL */
}
#endif
mandoc-1.14.3/compat_strlcpy.c 0100644 0002007 0000011 00000003133 13141336266 0015665 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_STRLCPY
int dummy;
#else
/* $OpenBSD: strlcpy.c,v 1.11 2006/05/05 15:27:38 millert Exp $ */
/*
* Copyright (c) 1998 Todd C. Miller
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#include
#include
/*
* Copy src to string dst of size siz. At most siz-1 characters
* will be copied. Always NUL terminates (unless siz == 0).
* Returns strlen(src); if retval >= siz, truncation occurred.
*/
size_t
strlcpy(char *dst, const char *src, size_t siz)
{
char *d = dst;
const char *s = src;
size_t n = siz;
/* Copy as many bytes as will fit */
if (n != 0) {
while (--n != 0) {
if ((*d++ = *s++) == '\0')
break;
}
}
/* Not enough room in dst, add NUL and traverse rest of src */
if (n == 0) {
if (siz != 0)
*d = '\0'; /* NUL-terminate dst */
while (*s++)
;
}
return(s - src - 1); /* count does not include NUL */
}
#endif
mandoc-1.14.3/compat_strsep.c 0100644 0002007 0000011 00000005061 13141336266 0015507 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_STRSEP
int dummy;
#else
/* $Id: compat_strsep.c,v 1.4 2014/12/11 09:05:01 schwarze Exp $ */
/* $OpenBSD: strsep.c,v 1.7 2014/02/05 20:42:32 stsp Exp $ */
/*-
* Copyright (c) 1990, 1993
* The Regents of the University of California. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the University nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*/
/*
* Get next token from string *stringp, where tokens are possibly-empty
* strings separated by characters from delim.
*
* Writes NULs into the string at *stringp to end tokens.
* delim need not remain constant from call to call.
* On return, *stringp points past the last NUL written (if there might
* be further tokens), or is NULL (if there are definitely no more tokens).
*
* If *stringp is NULL, strsep returns NULL.
*/
char *
strsep(char **stringp, const char *delim)
{
char *s;
const char *spanp;
int c, sc;
char *tok;
if ((s = *stringp) == NULL)
return (NULL);
for (tok = s;;) {
c = *s++;
spanp = delim;
do {
if ((sc = *spanp++) == c) {
if (c == 0)
s = NULL;
else
s[-1] = 0;
*stringp = s;
return (tok);
}
} while (sc != 0);
}
/* NOTREACHED */
}
#endif
mandoc-1.14.3/compat_strtonum.c 0100644 0002007 0000011 00000003606 13141336266 0016065 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_STRTONUM
int dummy;
#else
/* $Id: compat_strtonum.c,v 1.1 2015/02/16 14:56:22 schwarze Exp $ */
/* $OpenBSD: strtonum.c,v 1.7 2013/04/17 18:40:58 tedu Exp $ */
/*
* Copyright (c) 2004 Ted Unangst and Todd Miller
* All rights reserved.
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#include
#include
#include
#define INVALID 1
#define TOOSMALL 2
#define TOOLARGE 3
long long
strtonum(const char *numstr, long long minval, long long maxval,
const char **errstrp)
{
long long ll = 0;
int error = 0;
char *ep;
struct errval {
const char *errstr;
int err;
} ev[4] = {
{ NULL, 0 },
{ "invalid", EINVAL },
{ "too small", ERANGE },
{ "too large", ERANGE },
};
ev[0].err = errno;
errno = 0;
if (minval > maxval) {
error = INVALID;
} else {
ll = strtoll(numstr, &ep, 10);
if (numstr == ep || *ep != '\0')
error = INVALID;
else if ((ll == LLONG_MIN && errno == ERANGE) || ll < minval)
error = TOOSMALL;
else if ((ll == LLONG_MAX && errno == ERANGE) || ll > maxval)
error = TOOLARGE;
}
if (errstrp != NULL)
*errstrp = ev[error].errstr;
errno = ev[error].err;
if (error)
ll = 0;
return (ll);
}
#endif /* !HAVE_STRTONUM */
mandoc-1.14.3/compat_vasprintf.c 0100644 0002007 0000011 00000003064 13141336266 0016204 0 ustar 00schwarze wsrc #include "config.h"
#if HAVE_VASPRINTF
int dummy;
#else
/* $Id: compat_vasprintf.c,v 1.3 2015/10/06 18:32:19 schwarze Exp $ */
/*
* Copyright (c) 2015 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*
* This fallback implementation is not efficient:
* It does the formatting twice.
* Short of fiddling with the unknown internals of the system's
* printf(3) or completely reimplementing printf(3), i can't think
* of another portable solution.
*/
#include
#include
#include
int
vasprintf(char **ret, const char *format, va_list ap)
{
char buf[2];
va_list ap2;
int sz;
va_copy(ap2, ap);
sz = vsnprintf(buf, sizeof(buf), format, ap2);
va_end(ap2);
if (sz != -1 && (*ret = malloc(sz + 1)) != NULL) {
if (vsnprintf(*ret, sz + 1, format, ap) == sz)
return sz;
free(*ret);
}
*ret = NULL;
return -1;
}
#endif
mandoc-1.14.3/dba.c 0100644 0002007 0000011 00000032025 13141336266 0013352 0 ustar 00schwarze wsrc /* $Id: dba.c,v 1.10 2017/02/17 14:43:54 schwarze Exp $ */
/*
* Copyright (c) 2016, 2017 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*
* Allocation-based version of the mandoc database, for read-write access.
* The interface is defined in "dba.h".
*/
#include "config.h"
#include
#if HAVE_ENDIAN
#include
#elif HAVE_SYS_ENDIAN
#include
#elif HAVE_NTOHL
#include
#endif
#include
#include
#include
#include
#include
#include
#include "mandoc_aux.h"
#include "mandoc_ohash.h"
#include "mansearch.h"
#include "dba_write.h"
#include "dba_array.h"
#include "dba.h"
struct macro_entry {
struct dba_array *pages;
char value[];
};
static void *prepend(const char *, char);
static void dba_pages_write(struct dba_array *);
static int compare_names(const void *, const void *);
static int compare_strings(const void *, const void *);
static struct macro_entry
*get_macro_entry(struct ohash *, const char *, int32_t);
static void dba_macros_write(struct dba_array *);
static void dba_macro_write(struct ohash *);
static int compare_entries(const void *, const void *);
/*** top-level functions **********************************************/
struct dba *
dba_new(int32_t npages)
{
struct dba *dba;
struct ohash *macro;
int32_t im;
dba = mandoc_malloc(sizeof(*dba));
dba->pages = dba_array_new(npages, DBA_GROW);
dba->macros = dba_array_new(MACRO_MAX, 0);
for (im = 0; im < MACRO_MAX; im++) {
macro = mandoc_malloc(sizeof(*macro));
mandoc_ohash_init(macro, 4,
offsetof(struct macro_entry, value));
dba_array_set(dba->macros, im, macro);
}
return dba;
}
void
dba_free(struct dba *dba)
{
struct dba_array *page;
struct ohash *macro;
struct macro_entry *entry;
unsigned int slot;
dba_array_FOREACH(dba->macros, macro) {
for (entry = ohash_first(macro, &slot); entry != NULL;
entry = ohash_next(macro, &slot)) {
dba_array_free(entry->pages);
free(entry);
}
ohash_delete(macro);
free(macro);
}
dba_array_free(dba->macros);
dba_array_undel(dba->pages);
dba_array_FOREACH(dba->pages, page) {
dba_array_free(dba_array_get(page, DBP_NAME));
dba_array_free(dba_array_get(page, DBP_SECT));
dba_array_free(dba_array_get(page, DBP_ARCH));
free(dba_array_get(page, DBP_DESC));
dba_array_free(dba_array_get(page, DBP_FILE));
dba_array_free(page);
}
dba_array_free(dba->pages);
free(dba);
}
/*
* Write the complete mandoc database to disk; the format is:
* - One integer each for magic and version.
* - One pointer each to the macros table and to the final magic.
* - The pages table.
* - The macros table.
* - And at the very end, the magic integer again.
*/
int
dba_write(const char *fname, struct dba *dba)
{
int save_errno;
int32_t pos_end, pos_macros, pos_macros_ptr;
if (dba_open(fname) == -1)
return -1;
dba_int_write(MANDOCDB_MAGIC);
dba_int_write(MANDOCDB_VERSION);
pos_macros_ptr = dba_skip(1, 2);
dba_pages_write(dba->pages);
pos_macros = dba_tell();
dba_macros_write(dba->macros);
pos_end = dba_tell();
dba_int_write(MANDOCDB_MAGIC);
dba_seek(pos_macros_ptr);
dba_int_write(pos_macros);
dba_int_write(pos_end);
if (dba_close() == -1) {
save_errno = errno;
unlink(fname);
errno = save_errno;
return -1;
}
return 0;
}
/*** functions for handling pages *************************************/
/*
* Create a new page and append it to the pages table.
*/
struct dba_array *
dba_page_new(struct dba_array *pages, const char *arch,
const char *desc, const char *file, enum form form)
{
struct dba_array *page, *entry;
page = dba_array_new(DBP_MAX, 0);
entry = dba_array_new(1, DBA_STR | DBA_GROW);
dba_array_add(page, entry);
entry = dba_array_new(1, DBA_STR | DBA_GROW);
dba_array_add(page, entry);
if (arch != NULL && *arch != '\0') {
entry = dba_array_new(1, DBA_STR | DBA_GROW);
dba_array_add(entry, (void *)arch);
} else
entry = NULL;
dba_array_add(page, entry);
dba_array_add(page, mandoc_strdup(desc));
entry = dba_array_new(1, DBA_STR | DBA_GROW);
dba_array_add(entry, prepend(file, form));
dba_array_add(page, entry);
dba_array_add(pages, page);
return page;
}
/*
* Add a section, architecture, or file name to an existing page.
* Passing the NULL pointer for the architecture makes the page MI.
* In that case, any earlier or later architectures are ignored.
*/
void
dba_page_add(struct dba_array *page, int32_t ie, const char *str)
{
struct dba_array *entries;
char *entry;
entries = dba_array_get(page, ie);
if (ie == DBP_ARCH) {
if (entries == NULL)
return;
if (str == NULL || *str == '\0') {
dba_array_free(entries);
dba_array_set(page, DBP_ARCH, NULL);
return;
}
}
if (*str == '\0')
return;
dba_array_FOREACH(entries, entry) {
if (ie == DBP_FILE && *entry < ' ')
entry++;
if (strcmp(entry, str) == 0)
return;
}
dba_array_add(entries, (void *)str);
}
/*
* Add an additional name to an existing page.
*/
void
dba_page_alias(struct dba_array *page, const char *name, uint64_t mask)
{
struct dba_array *entries;
char *entry;
char maskbyte;
if (*name == '\0')
return;
maskbyte = mask & NAME_MASK;
entries = dba_array_get(page, DBP_NAME);
dba_array_FOREACH(entries, entry) {
if (strcmp(entry + 1, name) == 0) {
*entry |= maskbyte;
return;
}
}
dba_array_add(entries, prepend(name, maskbyte));
}
/*
* Return a pointer to a temporary copy of instr with inbyte prepended.
*/
static void *
prepend(const char *instr, char inbyte)
{
static char *outstr = NULL;
static size_t outlen = 0;
size_t newlen;
newlen = strlen(instr) + 1;
if (newlen > outlen) {
outstr = mandoc_realloc(outstr, newlen + 1);
outlen = newlen;
}
*outstr = inbyte;
memcpy(outstr + 1, instr, newlen);
return outstr;
}
/*
* Write the pages table to disk; the format is:
* - One integer containing the number of pages.
* - For each page, five pointers to the names, sections,
* architectures, description, and file names of the page.
* MI pages write 0 instead of the architecture pointer.
* - One list each for names, sections, architectures, descriptions and
* file names. The description for each page ends with a NUL byte.
* For all the other lists, each string ends with a NUL byte,
* and the last string for a page ends with two NUL bytes.
* - To assure alignment of following integers,
* the end is padded with NUL bytes up to a multiple of four bytes.
*/
static void
dba_pages_write(struct dba_array *pages)
{
struct dba_array *page, *entry;
int32_t pos_pages, pos_end;
pos_pages = dba_array_writelen(pages, 5);
dba_array_FOREACH(pages, page) {
dba_array_setpos(page, DBP_NAME, dba_tell());
entry = dba_array_get(page, DBP_NAME);
dba_array_sort(entry, compare_names);
dba_array_writelst(entry);
}
dba_array_FOREACH(pages, page) {
dba_array_setpos(page, DBP_SECT, dba_tell());
entry = dba_array_get(page, DBP_SECT);
dba_array_sort(entry, compare_strings);
dba_array_writelst(entry);
}
dba_array_FOREACH(pages, page) {
if ((entry = dba_array_get(page, DBP_ARCH)) != NULL) {
dba_array_setpos(page, DBP_ARCH, dba_tell());
dba_array_sort(entry, compare_strings);
dba_array_writelst(entry);
} else
dba_array_setpos(page, DBP_ARCH, 0);
}
dba_array_FOREACH(pages, page) {
dba_array_setpos(page, DBP_DESC, dba_tell());
dba_str_write(dba_array_get(page, DBP_DESC));
}
dba_array_FOREACH(pages, page) {
dba_array_setpos(page, DBP_FILE, dba_tell());
dba_array_writelst(dba_array_get(page, DBP_FILE));
}
pos_end = dba_align();
dba_seek(pos_pages);
dba_array_FOREACH(pages, page)
dba_array_writepos(page);
dba_seek(pos_end);
}
static int
compare_names(const void *vp1, const void *vp2)
{
const char *cp1, *cp2;
int diff;
cp1 = *(const char * const *)vp1;
cp2 = *(const char * const *)vp2;
return (diff = *cp2 - *cp1) ? diff :
strcasecmp(cp1 + 1, cp2 + 1);
}
static int
compare_strings(const void *vp1, const void *vp2)
{
const char *cp1, *cp2;
cp1 = *(const char * const *)vp1;
cp2 = *(const char * const *)vp2;
return strcmp(cp1, cp2);
}
/*** functions for handling macros ************************************/
/*
* In the hash table for a single macro, look up an entry by
* the macro value or add an empty one if it doesn't exist yet.
*/
static struct macro_entry *
get_macro_entry(struct ohash *macro, const char *value, int32_t np)
{
struct macro_entry *entry;
size_t len;
unsigned int slot;
slot = ohash_qlookup(macro, value);
if ((entry = ohash_find(macro, slot)) == NULL) {
len = strlen(value) + 1;
entry = mandoc_malloc(sizeof(*entry) + len);
memcpy(&entry->value, value, len);
entry->pages = dba_array_new(np, DBA_GROW);
ohash_insert(macro, slot, entry);
}
return entry;
}
/*
* In addition to get_macro_entry(), add multiple page references,
* converting them from the on-disk format (byte offsets in the file)
* to page pointers in memory.
*/
void
dba_macro_new(struct dba *dba, int32_t im, const char *value,
const int32_t *pp)
{
struct macro_entry *entry;
const int32_t *ip;
int32_t np;
np = 0;
for (ip = pp; *ip; ip++)
np++;
entry = get_macro_entry(dba_array_get(dba->macros, im), value, np);
for (ip = pp; *ip; ip++)
dba_array_add(entry->pages, dba_array_get(dba->pages,
be32toh(*ip) / 5 / sizeof(*ip) - 1));
}
/*
* In addition to get_macro_entry(), add one page reference,
* directly taking the in-memory page pointer as an argument.
*/
void
dba_macro_add(struct dba_array *macros, int32_t im, const char *value,
struct dba_array *page)
{
struct macro_entry *entry;
if (*value == '\0')
return;
entry = get_macro_entry(dba_array_get(macros, im), value, 1);
dba_array_add(entry->pages, page);
}
/*
* Write the macros table to disk; the format is:
* - The number of macro tables (actually, MACRO_MAX).
* - That number of pointers to the individual macro tables.
* - The individual macro tables.
*/
static void
dba_macros_write(struct dba_array *macros)
{
struct ohash *macro;
int32_t im, pos_macros, pos_end;
pos_macros = dba_array_writelen(macros, 1);
im = 0;
dba_array_FOREACH(macros, macro) {
dba_array_setpos(macros, im++, dba_tell());
dba_macro_write(macro);
}
pos_end = dba_tell();
dba_seek(pos_macros);
dba_array_writepos(macros);
dba_seek(pos_end);
}
/*
* Write one individual macro table to disk; the format is:
* - The number of entries in the table.
* - For each entry, two pointers, the first one to the value
* and the second one to the list of pages.
* - A list of values, each ending in a NUL byte.
* - To assure alignment of following integers,
* padding with NUL bytes up to a multiple of four bytes.
* - A list of pointers to pages, each list ending in a 0 integer.
*/
static void
dba_macro_write(struct ohash *macro)
{
struct macro_entry **entries, *entry;
struct dba_array *page;
int32_t *kpos, *dpos;
unsigned int ie, ne, slot;
int use;
int32_t addr, pos_macro, pos_end;
/* Temporary storage for filtering and sorting. */
ne = ohash_entries(macro);
entries = mandoc_reallocarray(NULL, ne, sizeof(*entries));
kpos = mandoc_reallocarray(NULL, ne, sizeof(*kpos));
dpos = mandoc_reallocarray(NULL, ne, sizeof(*dpos));
/* Build a list of non-empty entries and sort it. */
ne = 0;
for (entry = ohash_first(macro, &slot); entry != NULL;
entry = ohash_next(macro, &slot)) {
use = 0;
dba_array_FOREACH(entry->pages, page)
if (dba_array_getpos(page))
use = 1;
if (use)
entries[ne++] = entry;
}
qsort(entries, ne, sizeof(*entries), compare_entries);
/* Number of entries, and space for the pointer pairs. */
dba_int_write(ne);
pos_macro = dba_skip(2, ne);
/* String table. */
for (ie = 0; ie < ne; ie++) {
kpos[ie] = dba_tell();
dba_str_write(entries[ie]->value);
}
dba_align();
/* Pages table. */
for (ie = 0; ie < ne; ie++) {
dpos[ie] = dba_tell();
dba_array_FOREACH(entries[ie]->pages, page)
if ((addr = dba_array_getpos(page)))
dba_int_write(addr);
dba_int_write(0);
}
pos_end = dba_tell();
/* Fill in the pointer pairs. */
dba_seek(pos_macro);
for (ie = 0; ie < ne; ie++) {
dba_int_write(kpos[ie]);
dba_int_write(dpos[ie]);
}
dba_seek(pos_end);
free(entries);
free(kpos);
free(dpos);
}
static int
compare_entries(const void *vp1, const void *vp2)
{
const struct macro_entry *ep1, *ep2;
ep1 = *(const struct macro_entry * const *)vp1;
ep2 = *(const struct macro_entry * const *)vp2;
return strcmp(ep1->value, ep2->value);
}
mandoc-1.14.3/dba_array.c 0100644 0002007 0000011 00000010356 13141336266 0014553 0 ustar 00schwarze wsrc /* $Id: dba_array.c,v 1.1 2016/07/19 21:31:55 schwarze Exp $ */
/*
* Copyright (c) 2016 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*
* Allocation-based arrays for the mandoc database, for read-write access.
* The interface is defined in "dba_array.h".
*/
#include
#include
#include
#include
#include "mandoc_aux.h"
#include "dba_write.h"
#include "dba_array.h"
struct dba_array {
void **ep; /* Array of entries. */
int32_t *em; /* Array of map positions. */
int flags;
int32_t ea; /* Entries allocated. */
int32_t eu; /* Entries used (including deleted). */
int32_t ed; /* Entries deleted. */
int32_t ec; /* Currently active entry. */
int32_t pos; /* Map position of this array. */
};
struct dba_array *
dba_array_new(int32_t ea, int flags)
{
struct dba_array *array;
assert(ea > 0);
array = mandoc_malloc(sizeof(*array));
array->ep = mandoc_reallocarray(NULL, ea, sizeof(*array->ep));
array->em = mandoc_reallocarray(NULL, ea, sizeof(*array->em));
array->ea = ea;
array->eu = 0;
array->ed = 0;
array->ec = 0;
array->flags = flags;
array->pos = 0;
return array;
}
void
dba_array_free(struct dba_array *array)
{
int32_t ie;
if (array == NULL)
return;
if (array->flags & DBA_STR)
for (ie = 0; ie < array->eu; ie++)
free(array->ep[ie]);
free(array->ep);
free(array->em);
free(array);
}
void
dba_array_set(struct dba_array *array, int32_t ie, void *entry)
{
assert(ie >= 0);
assert(ie < array->ea);
assert(ie <= array->eu);
if (ie == array->eu)
array->eu++;
if (array->flags & DBA_STR)
entry = mandoc_strdup(entry);
array->ep[ie] = entry;
array->em[ie] = 0;
}
void
dba_array_add(struct dba_array *array, void *entry)
{
if (array->eu == array->ea) {
assert(array->flags & DBA_GROW);
array->ep = mandoc_reallocarray(array->ep,
2, sizeof(*array->ep) * array->ea);
array->em = mandoc_reallocarray(array->em,
2, sizeof(*array->em) * array->ea);
array->ea *= 2;
}
dba_array_set(array, array->eu, entry);
}
void *
dba_array_get(struct dba_array *array, int32_t ie)
{
if (ie < 0 || ie >= array->eu || array->em[ie] == -1)
return NULL;
return array->ep[ie];
}
void
dba_array_start(struct dba_array *array)
{
array->ec = array->eu;
}
void *
dba_array_next(struct dba_array *array)
{
if (array->ec < array->eu)
array->ec++;
else
array->ec = 0;
while (array->ec < array->eu && array->em[array->ec] == -1)
array->ec++;
return array->ec < array->eu ? array->ep[array->ec] : NULL;
}
void
dba_array_del(struct dba_array *array)
{
if (array->ec < array->eu && array->em[array->ec] != -1) {
array->em[array->ec] = -1;
array->ed++;
}
}
void
dba_array_undel(struct dba_array *array)
{
memset(array->em, 0, sizeof(*array->em) * array->eu);
}
void
dba_array_setpos(struct dba_array *array, int32_t ie, int32_t pos)
{
array->em[ie] = pos;
}
int32_t
dba_array_getpos(struct dba_array *array)
{
return array->pos;
}
void
dba_array_sort(struct dba_array *array, dba_compare_func func)
{
assert(array->ed == 0);
qsort(array->ep, array->eu, sizeof(*array->ep), func);
}
int32_t
dba_array_writelen(struct dba_array *array, int32_t nmemb)
{
dba_int_write(array->eu - array->ed);
return dba_skip(nmemb, array->eu - array->ed);
}
void
dba_array_writepos(struct dba_array *array)
{
int32_t ie;
array->pos = dba_tell();
for (ie = 0; ie < array->eu; ie++)
if (array->em[ie] != -1)
dba_int_write(array->em[ie]);
}
void
dba_array_writelst(struct dba_array *array)
{
const char *str;
dba_array_FOREACH(array, str)
dba_str_write(str);
dba_char_write('\0');
}
mandoc-1.14.3/dba_read.c 0100644 0002007 0000011 00000004520 13141336266 0014344 0 ustar 00schwarze wsrc /* $Id: dba_read.c,v 1.4 2016/08/17 20:46:56 schwarze Exp $ */
/*
* Copyright (c) 2016 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*
* Function to read the mandoc database from disk into RAM,
* such that data can be added or removed.
* The interface is defined in "dba.h".
* This file is seperate from dba.c because this also uses "dbm.h".
*/
#include
#include
#include
#include
#include
#include "mandoc_aux.h"
#include "mansearch.h"
#include "dba_array.h"
#include "dba.h"
#include "dbm.h"
struct dba *
dba_read(const char *fname)
{
struct dba *dba;
struct dba_array *page;
struct dbm_page *pdata;
struct dbm_macro *mdata;
const char *cp;
int32_t im, ip, iv, npages;
if (dbm_open(fname) == -1)
return NULL;
npages = dbm_page_count();
dba = dba_new(npages < 128 ? 128 : npages);
for (ip = 0; ip < npages; ip++) {
pdata = dbm_page_get(ip);
page = dba_page_new(dba->pages, pdata->arch,
pdata->desc, pdata->file + 1, *pdata->file);
for (cp = pdata->name; *cp != '\0'; cp = strchr(cp, '\0') + 1)
dba_page_add(page, DBP_NAME, cp);
for (cp = pdata->sect; *cp != '\0'; cp = strchr(cp, '\0') + 1)
dba_page_add(page, DBP_SECT, cp);
if ((cp = pdata->arch) != NULL)
while (*(cp = strchr(cp, '\0') + 1) != '\0')
dba_page_add(page, DBP_ARCH, cp);
cp = pdata->file;
while (*(cp = strchr(cp, '\0') + 1) != '\0')
dba_page_add(page, DBP_FILE, cp);
}
for (im = 0; im < MACRO_MAX; im++) {
for (iv = 0; iv < dbm_macro_count(im); iv++) {
mdata = dbm_macro_get(im, iv);
dba_macro_new(dba, im, mdata->value, mdata->pp);
}
}
dbm_close();
return dba;
}
mandoc-1.14.3/dba_write.c 0100644 0002007 0000011 00000004663 13141336266 0014573 0 ustar 00schwarze wsrc /* $Id: dba_write.c,v 1.3 2016/08/05 23:15:08 schwarze Exp $ */
/*
* Copyright (c) 2016 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*
* Low-level functions for serializing allocation-based data to disk.
* The interface is defined in "dba_write.h".
*/
#include "config.h"
#include
#if HAVE_ENDIAN
#include
#elif HAVE_SYS_ENDIAN
#include
#elif HAVE_NTOHL
#include
#endif
#if HAVE_ERR
#include
#endif
#include
#include
#include
#include
#include "dba_write.h"
static FILE *ofp;
int
dba_open(const char *fname)
{
ofp = fopen(fname, "w");
return ofp == NULL ? -1 : 0;
}
int
dba_close(void)
{
return fclose(ofp) == EOF ? -1 : 0;
}
int32_t
dba_tell(void)
{
long pos;
if ((pos = ftell(ofp)) == -1)
err(1, "ftell");
if (pos >= INT32_MAX) {
errno = EOVERFLOW;
err(1, "ftell = %ld", pos);
}
return pos;
}
void
dba_seek(int32_t pos)
{
if (fseek(ofp, pos, SEEK_SET) == -1)
err(1, "fseek(%d)", pos);
}
int32_t
dba_align(void)
{
int32_t pos;
pos = dba_tell();
while (pos & 3) {
dba_char_write('\0');
pos++;
}
return pos;
}
int32_t
dba_skip(int32_t nmemb, int32_t sz)
{
const int32_t out[5] = {0, 0, 0, 0, 0};
int32_t i, pos;
assert(sz >= 0);
assert(nmemb > 0);
assert(nmemb <= 5);
pos = dba_tell();
for (i = 0; i < sz; i++)
if (nmemb - fwrite(&out, sizeof(out[0]), nmemb, ofp))
err(1, "fwrite");
return pos;
}
void
dba_char_write(int c)
{
if (putc(c, ofp) == EOF)
err(1, "fputc");
}
void
dba_str_write(const char *str)
{
if (fputs(str, ofp) == EOF)
err(1, "fputs");
dba_char_write('\0');
}
void
dba_int_write(int32_t i)
{
i = htobe32(i);
if (fwrite(&i, sizeof(i), 1, ofp) != 1)
err(1, "fwrite");
}
mandoc-1.14.3/dbm.c 0100644 0002007 0000011 00000022437 13141336266 0013374 0 ustar 00schwarze wsrc /* $Id: dbm.c,v 1.5 2016/10/18 22:27:25 schwarze Exp $ */
/*
* Copyright (c) 2016 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*
* Map-based version of the mandoc database, for read-only access.
* The interface is defined in "dbm.h".
*/
#include "config.h"
#include
#if HAVE_ENDIAN
#include
#elif HAVE_SYS_ENDIAN
#include
#elif HAVE_NTOHL
#include
#endif
#if HAVE_ERR
#include
#endif
#include
#include
#include
#include
#include
#include
#include "mansearch.h"
#include "dbm_map.h"
#include "dbm.h"
struct macro {
int32_t value;
int32_t pages;
};
struct page {
int32_t name;
int32_t sect;
int32_t arch;
int32_t desc;
int32_t file;
};
enum iter {
ITER_NONE = 0,
ITER_NAME,
ITER_SECT,
ITER_ARCH,
ITER_DESC,
ITER_MACRO
};
static struct macro *macros[MACRO_MAX];
static int32_t nvals[MACRO_MAX];
static struct page *pages;
static int32_t npages;
static enum iter iteration;
static struct dbm_res page_bytitle(enum iter, const struct dbm_match *);
static struct dbm_res page_byarch(const struct dbm_match *);
static struct dbm_res page_bymacro(int32_t, const struct dbm_match *);
static char *macro_bypage(int32_t, int32_t);
/*** top level functions **********************************************/
/*
* Open a disk-based mandoc database for read-only access.
* Map the pages and macros[] arrays.
* Return 0 on success. Return -1 and set errno on failure.
*/
int
dbm_open(const char *fname)
{
const int32_t *mp, *ep;
int32_t im;
if (dbm_map(fname) == -1)
return -1;
if ((npages = be32toh(*dbm_getint(4))) < 0) {
warnx("dbm_open(%s): Invalid number of pages: %d",
fname, npages);
goto fail;
}
pages = (struct page *)dbm_getint(5);
if ((mp = dbm_get(*dbm_getint(2))) == NULL) {
warnx("dbm_open(%s): Invalid offset of macros array", fname);
goto fail;
}
if (be32toh(*mp) != MACRO_MAX) {
warnx("dbm_open(%s): Invalid number of macros: %d",
fname, be32toh(*mp));
goto fail;
}
for (im = 0; im < MACRO_MAX; im++) {
if ((ep = dbm_get(*++mp)) == NULL) {
warnx("dbm_open(%s): Invalid offset of macro %d",
fname, im);
goto fail;
}
nvals[im] = be32toh(*ep);
macros[im] = (struct macro *)++ep;
}
return 0;
fail:
dbm_unmap();
errno = EFTYPE;
return -1;
}
void
dbm_close(void)
{
dbm_unmap();
}
/*** functions for handling pages *************************************/
int32_t
dbm_page_count(void)
{
return npages;
}
/*
* Give the caller pointers to the data for one manual page.
*/
struct dbm_page *
dbm_page_get(int32_t ip)
{
static struct dbm_page res;
assert(ip >= 0);
assert(ip < npages);
res.name = dbm_get(pages[ip].name);
if (res.name == NULL)
res.name = "(NULL)";
res.sect = dbm_get(pages[ip].sect);
if (res.sect == NULL)
res.sect = "(NULL)";
res.arch = pages[ip].arch ? dbm_get(pages[ip].arch) : NULL;
res.desc = dbm_get(pages[ip].desc);
if (res.desc == NULL)
res.desc = "(NULL)";
res.file = dbm_get(pages[ip].file);
if (res.file == NULL)
res.file = " (NULL)";
res.addr = dbm_addr(pages + ip);
return &res;
}
/*
* Functions to start filtered iterations over manual pages.
*/
void
dbm_page_byname(const struct dbm_match *match)
{
assert(match != NULL);
page_bytitle(ITER_NAME, match);
}
void
dbm_page_bysect(const struct dbm_match *match)
{
assert(match != NULL);
page_bytitle(ITER_SECT, match);
}
void
dbm_page_byarch(const struct dbm_match *match)
{
assert(match != NULL);
page_byarch(match);
}
void
dbm_page_bydesc(const struct dbm_match *match)
{
assert(match != NULL);
page_bytitle(ITER_DESC, match);
}
void
dbm_page_bymacro(int32_t im, const struct dbm_match *match)
{
assert(im >= 0);
assert(im < MACRO_MAX);
assert(match != NULL);
page_bymacro(im, match);
}
/*
* Return the number of the next manual page in the current iteration.
*/
struct dbm_res
dbm_page_next(void)
{
struct dbm_res res = {-1, 0};
switch(iteration) {
case ITER_NONE:
return res;
case ITER_ARCH:
return page_byarch(NULL);
case ITER_MACRO:
return page_bymacro(0, NULL);
default:
return page_bytitle(iteration, NULL);
}
}
/*
* Functions implementing the iteration over manual pages.
*/
static struct dbm_res
page_bytitle(enum iter arg_iter, const struct dbm_match *arg_match)
{
static const struct dbm_match *match;
static const char *cp;
static int32_t ip;
struct dbm_res res = {-1, 0};
assert(arg_iter == ITER_NAME || arg_iter == ITER_DESC ||
arg_iter == ITER_SECT);
/* Initialize for a new iteration. */
if (arg_match != NULL) {
iteration = arg_iter;
match = arg_match;
switch (iteration) {
case ITER_NAME:
cp = dbm_get(pages[0].name);
break;
case ITER_SECT:
cp = dbm_get(pages[0].sect);
break;
case ITER_DESC:
cp = dbm_get(pages[0].desc);
break;
default:
abort();
}
if (cp == NULL) {
iteration = ITER_NONE;
match = NULL;
cp = NULL;
ip = npages;
} else
ip = 0;
return res;
}
/* Search for a name. */
while (ip < npages) {
if (iteration == ITER_NAME)
cp++;
if (dbm_match(match, cp))
break;
cp = strchr(cp, '\0') + 1;
if (iteration == ITER_DESC)
ip++;
else if (*cp == '\0') {
cp++;
ip++;
}
}
/* Reached the end without a match. */
if (ip == npages) {
iteration = ITER_NONE;
match = NULL;
cp = NULL;
return res;
}
/* Found a match; save the quality for later retrieval. */
res.page = ip;
res.bits = iteration == ITER_NAME ? cp[-1] : 0;
/* Skip the remaining names of this page. */
if (++ip < npages) {
do {
cp++;
} while (cp[-1] != '\0' ||
(iteration != ITER_DESC && cp[-2] != '\0'));
}
return res;
}
static struct dbm_res
page_byarch(const struct dbm_match *arg_match)
{
static const struct dbm_match *match;
struct dbm_res res = {-1, 0};
static int32_t ip;
const char *cp;
/* Initialize for a new iteration. */
if (arg_match != NULL) {
iteration = ITER_ARCH;
match = arg_match;
ip = 0;
return res;
}
/* Search for an architecture. */
for ( ; ip < npages; ip++)
if (pages[ip].arch)
for (cp = dbm_get(pages[ip].arch);
*cp != '\0';
cp = strchr(cp, '\0') + 1)
if (dbm_match(match, cp)) {
res.page = ip++;
return res;
}
/* Reached the end without a match. */
iteration = ITER_NONE;
match = NULL;
return res;
}
static struct dbm_res
page_bymacro(int32_t arg_im, const struct dbm_match *arg_match)
{
static const struct dbm_match *match;
static const int32_t *pp;
static const char *cp;
static int32_t im, iv;
struct dbm_res res = {-1, 0};
assert(im >= 0);
assert(im < MACRO_MAX);
/* Initialize for a new iteration. */
if (arg_match != NULL) {
iteration = ITER_MACRO;
match = arg_match;
im = arg_im;
cp = nvals[im] ? dbm_get(macros[im]->value) : NULL;
pp = NULL;
iv = -1;
return res;
}
if (iteration != ITER_MACRO)
return res;
/* Find the next matching macro value. */
while (pp == NULL || *pp == 0) {
if (++iv == nvals[im]) {
iteration = ITER_NONE;
return res;
}
if (iv)
cp = strchr(cp, '\0') + 1;
if (dbm_match(match, cp))
pp = dbm_get(macros[im][iv].pages);
}
/* Found a matching page. */
res.page = (struct page *)dbm_get(*pp++) - pages;
return res;
}
/*** functions for handling macros ************************************/
int32_t
dbm_macro_count(int32_t im)
{
assert(im >= 0);
assert(im < MACRO_MAX);
return nvals[im];
}
struct dbm_macro *
dbm_macro_get(int32_t im, int32_t iv)
{
static struct dbm_macro macro;
assert(im >= 0);
assert(im < MACRO_MAX);
assert(iv >= 0);
assert(iv < nvals[im]);
macro.value = dbm_get(macros[im][iv].value);
macro.pp = dbm_get(macros[im][iv].pages);
return ¯o;
}
/*
* Filtered iteration over macro entries.
*/
void
dbm_macro_bypage(int32_t im, int32_t ip)
{
assert(im >= 0);
assert(im < MACRO_MAX);
assert(ip != 0);
macro_bypage(im, ip);
}
char *
dbm_macro_next(void)
{
return macro_bypage(MACRO_MAX, 0);
}
static char *
macro_bypage(int32_t arg_im, int32_t arg_ip)
{
static const int32_t *pp;
static int32_t im, ip, iv;
/* Initialize for a new iteration. */
if (arg_im < MACRO_MAX && arg_ip != 0) {
im = arg_im;
ip = arg_ip;
pp = dbm_get(macros[im]->pages);
iv = 0;
return NULL;
}
if (im >= MACRO_MAX)
return NULL;
/* Search for the next value. */
while (iv < nvals[im]) {
if (*pp == ip)
break;
if (*pp == 0)
iv++;
pp++;
}
/* Reached the end without a match. */
if (iv == nvals[im]) {
im = MACRO_MAX;
ip = 0;
pp = NULL;
return NULL;
}
/* Found a match; skip the remaining pages of this entry. */
if (++iv < nvals[im])
while (*pp++ != 0)
continue;
return dbm_get(macros[im][iv - 1].value);
}
mandoc-1.14.3/dbm_map.c 0100644 0002007 0000011 00000011260 13141336266 0014221 0 ustar 00schwarze wsrc /* $Id: dbm_map.c,v 1.8 2017/02/17 14:43:54 schwarze Exp $ */
/*
* Copyright (c) 2016 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*
* Low-level routines for the map-based version
* of the mandoc database, for read-only access.
* The interface is defined in "dbm_map.h".
*/
#include "config.h"
#include
#include
#include
#if HAVE_ENDIAN
#include
#elif HAVE_SYS_ENDIAN
#include
#elif HAVE_NTOHL
#include
#endif
#if HAVE_ERR
#include
#endif
#include
#include
#include
#include
#include
#include
#include
#include "mansearch.h"
#include "dbm_map.h"
#include "dbm.h"
static struct stat st;
static char *dbm_base;
static int ifd;
static int32_t max_offset;
/*
* Open a disk-based database for read-only access.
* Validate the file format as far as it is not mandoc-specific.
* Return 0 on success. Return -1 and set errno on failure.
*/
int
dbm_map(const char *fname)
{
int save_errno;
const int32_t *magic;
if ((ifd = open(fname, O_RDONLY)) == -1)
return -1;
if (fstat(ifd, &st) == -1)
goto fail;
if (st.st_size < 5) {
warnx("dbm_map(%s): File too short", fname);
errno = EFTYPE;
goto fail;
}
if (st.st_size > INT32_MAX) {
errno = EFBIG;
goto fail;
}
if ((dbm_base = mmap(NULL, st.st_size, PROT_READ, MAP_SHARED,
ifd, 0)) == MAP_FAILED)
goto fail;
magic = dbm_getint(0);
if (be32toh(*magic) != MANDOCDB_MAGIC) {
if (strncmp(dbm_base, "SQLite format 3", 15))
warnx("dbm_map(%s): "
"Bad initial magic %x (expected %x)",
fname, be32toh(*magic), MANDOCDB_MAGIC);
else
warnx("dbm_map(%s): "
"Obsolete format based on SQLite 3",
fname);
errno = EFTYPE;
goto fail;
}
magic = dbm_getint(1);
if (be32toh(*magic) != MANDOCDB_VERSION) {
warnx("dbm_map(%s): Bad version number %d (expected %d)",
fname, be32toh(*magic), MANDOCDB_VERSION);
errno = EFTYPE;
goto fail;
}
max_offset = be32toh(*dbm_getint(3)) + sizeof(int32_t);
if (st.st_size != max_offset) {
warnx("dbm_map(%s): Inconsistent file size %lld (expected %d)",
fname, (long long)st.st_size, max_offset);
errno = EFTYPE;
goto fail;
}
if ((magic = dbm_get(*dbm_getint(3))) == NULL) {
errno = EFTYPE;
goto fail;
}
if (be32toh(*magic) != MANDOCDB_MAGIC) {
warnx("dbm_map(%s): Bad final magic %x (expected %x)",
fname, be32toh(*magic), MANDOCDB_MAGIC);
errno = EFTYPE;
goto fail;
}
return 0;
fail:
save_errno = errno;
close(ifd);
errno = save_errno;
return -1;
}
void
dbm_unmap(void)
{
if (munmap(dbm_base, st.st_size) == -1)
warn("dbm_unmap: munmap");
if (close(ifd) == -1)
warn("dbm_unmap: close");
dbm_base = (char *)-1;
}
/*
* Take a raw integer as it was read from the database.
* Interpret it as an offset into the database file
* and return a pointer to that place in the file.
*/
void *
dbm_get(int32_t offset)
{
offset = be32toh(offset);
if (offset < 0) {
warnx("dbm_get: Database corrupt: offset %d", offset);
return NULL;
}
if (offset >= max_offset) {
warnx("dbm_get: Database corrupt: offset %d > %d",
offset, max_offset);
return NULL;
}
return dbm_base + offset;
}
/*
* Assume the database starts with some integers.
* Assume they are numbered starting from 0, increasing.
* Get a pointer to one with the number "offset".
*/
int32_t *
dbm_getint(int32_t offset)
{
return (int32_t *)dbm_base + offset;
}
/*
* The reverse of dbm_get().
* Take pointer into the database file
* and convert it to the raw integer
* that would be used to refer to that place in the file.
*/
int32_t
dbm_addr(const void *p)
{
return htobe32((const char *)p - dbm_base);
}
int
dbm_match(const struct dbm_match *match, const char *str)
{
switch (match->type) {
case DBM_EXACT:
return strcmp(str, match->str) == 0;
case DBM_SUB:
return strcasestr(str, match->str) != NULL;
case DBM_REGEX:
return regexec(match->re, str, 0, NULL, 0) == 0;
default:
abort();
}
}
mandoc-1.14.3/demandoc.c 0100644 0002007 0000011 00000012361 13141336266 0014377 0 ustar 00schwarze wsrc /* $Id: demandoc.c,v 1.29 2017/06/24 14:38:32 schwarze Exp $ */
/*
* Copyright (c) 2011 Kristaps Dzonsons
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#include "config.h"
#include
#include
#include
#include
#include
#include
#include
#include "mandoc.h"
#include "roff.h"
#include "man.h"
#include "mdoc.h"
static void pline(int, int *, int *, int);
static void pman(const struct roff_node *, int *, int *, int);
static void pmandoc(struct mparse *, int, const char *, int);
static void pmdoc(const struct roff_node *, int *, int *, int);
static void pstring(const char *, int, int *, int);
static void usage(void);
static const char *progname;
int
main(int argc, char *argv[])
{
struct mparse *mp;
int ch, fd, i, list;
extern int optind;
if (argc < 1)
progname = "demandoc";
else if ((progname = strrchr(argv[0], '/')) == NULL)
progname = argv[0];
else
++progname;
mp = NULL;
list = 0;
while (-1 != (ch = getopt(argc, argv, "ikm:pw")))
switch (ch) {
case ('i'):
/* FALLTHROUGH */
case ('k'):
/* FALLTHROUGH */
case ('m'):
/* FALLTHROUGH */
case ('p'):
break;
case ('w'):
list = 1;
break;
default:
usage();
return (int)MANDOCLEVEL_BADARG;
}
argc -= optind;
argv += optind;
mchars_alloc();
mp = mparse_alloc(MPARSE_SO, MANDOCERR_MAX, NULL,
MANDOC_OS_OTHER, NULL);
assert(mp);
if (argc < 1)
pmandoc(mp, STDIN_FILENO, "", list);
for (i = 0; i < argc; i++) {
mparse_reset(mp);
if ((fd = mparse_open(mp, argv[i])) == -1) {
perror(argv[i]);
continue;
}
pmandoc(mp, fd, argv[i], list);
}
mparse_free(mp);
mchars_free();
return (int)MANDOCLEVEL_OK;
}
static void
usage(void)
{
fprintf(stderr, "usage: %s [-w] [files...]\n", progname);
}
static void
pmandoc(struct mparse *mp, int fd, const char *fn, int list)
{
struct roff_man *man;
int line, col;
mparse_readfd(mp, fd, fn);
close(fd);
mparse_result(mp, &man, NULL);
line = 1;
col = 0;
if (man == NULL)
return;
if (man->macroset == MACROSET_MDOC) {
mdoc_validate(man);
pmdoc(man->first->child, &line, &col, list);
} else {
man_validate(man);
pman(man->first->child, &line, &col, list);
}
if ( ! list)
putchar('\n');
}
/*
* Strip the escapes out of a string, emitting the results.
*/
static void
pstring(const char *p, int col, int *colp, int list)
{
enum mandoc_esc esc;
const char *start, *end;
int emit;
/*
* Print as many column spaces til we achieve parity with the
* input document.
*/
again:
if (list && '\0' != *p) {
while (isspace((unsigned char)*p))
p++;
while ('\'' == *p || '(' == *p || '"' == *p)
p++;
emit = isalpha((unsigned char)p[0]) &&
isalpha((unsigned char)p[1]);
for (start = p; '\0' != *p; p++)
if ('\\' == *p) {
p++;
esc = mandoc_escape(&p, NULL, NULL);
if (ESCAPE_ERROR == esc)
return;
emit = 0;
} else if (isspace((unsigned char)*p))
break;
end = p - 1;
while (end > start)
if ('.' == *end || ',' == *end ||
'\'' == *end || '"' == *end ||
')' == *end || '!' == *end ||
'?' == *end || ':' == *end ||
';' == *end)
end--;
else
break;
if (emit && end - start >= 1) {
for ( ; start <= end; start++)
if (ASCII_HYPH == *start)
putchar('-');
else
putchar((unsigned char)*start);
putchar('\n');
}
if (isspace((unsigned char)*p))
goto again;
return;
}
while (*colp < col) {
putchar(' ');
(*colp)++;
}
/*
* Print the input word, skipping any special characters.
*/
while ('\0' != *p)
if ('\\' == *p) {
p++;
esc = mandoc_escape(&p, NULL, NULL);
if (ESCAPE_ERROR == esc)
break;
} else {
putchar((unsigned char )*p++);
(*colp)++;
}
}
static void
pline(int line, int *linep, int *col, int list)
{
if (list)
return;
/*
* Print out as many lines as needed to reach parity with the
* original input.
*/
while (*linep < line) {
putchar('\n');
(*linep)++;
}
*col = 0;
}
static void
pmdoc(const struct roff_node *p, int *line, int *col, int list)
{
for ( ; p; p = p->next) {
if (NODE_LINE & p->flags)
pline(p->line, line, col, list);
if (ROFFT_TEXT == p->type)
pstring(p->string, p->pos, col, list);
if (p->child)
pmdoc(p->child, line, col, list);
}
}
static void
pman(const struct roff_node *p, int *line, int *col, int list)
{
for ( ; p; p = p->next) {
if (NODE_LINE & p->flags)
pline(p->line, line, col, list);
if (ROFFT_TEXT == p->type)
pstring(p->string, p->pos, col, list);
if (p->child)
pman(p->child, line, col, list);
}
}
mandoc-1.14.3/eqn.c 0100644 0002007 0000011 00000066215 13141336266 0013417 0 ustar 00schwarze wsrc /* $Id: eqn.c,v 1.78 2017/07/15 16:26:17 schwarze Exp $ */
/*
* Copyright (c) 2011, 2014 Kristaps Dzonsons
* Copyright (c) 2014, 2015, 2017 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#include "config.h"
#include
#include
#include
#include
#include
#include
#include
#include
#include "mandoc_aux.h"
#include "mandoc.h"
#include "roff.h"
#include "libmandoc.h"
#include "libroff.h"
#define EQN_NEST_MAX 128 /* maximum nesting of defines */
#define STRNEQ(p1, sz1, p2, sz2) \
((sz1) == (sz2) && 0 == strncmp((p1), (p2), (sz1)))
enum eqn_tok {
EQN_TOK_DYAD = 0,
EQN_TOK_VEC,
EQN_TOK_UNDER,
EQN_TOK_BAR,
EQN_TOK_TILDE,
EQN_TOK_HAT,
EQN_TOK_DOT,
EQN_TOK_DOTDOT,
EQN_TOK_FWD,
EQN_TOK_BACK,
EQN_TOK_DOWN,
EQN_TOK_UP,
EQN_TOK_FAT,
EQN_TOK_ROMAN,
EQN_TOK_ITALIC,
EQN_TOK_BOLD,
EQN_TOK_SIZE,
EQN_TOK_SUB,
EQN_TOK_SUP,
EQN_TOK_SQRT,
EQN_TOK_OVER,
EQN_TOK_FROM,
EQN_TOK_TO,
EQN_TOK_BRACE_OPEN,
EQN_TOK_BRACE_CLOSE,
EQN_TOK_GSIZE,
EQN_TOK_GFONT,
EQN_TOK_MARK,
EQN_TOK_LINEUP,
EQN_TOK_LEFT,
EQN_TOK_RIGHT,
EQN_TOK_PILE,
EQN_TOK_LPILE,
EQN_TOK_RPILE,
EQN_TOK_CPILE,
EQN_TOK_MATRIX,
EQN_TOK_CCOL,
EQN_TOK_LCOL,
EQN_TOK_RCOL,
EQN_TOK_DELIM,
EQN_TOK_DEFINE,
EQN_TOK_TDEFINE,
EQN_TOK_NDEFINE,
EQN_TOK_UNDEF,
EQN_TOK_ABOVE,
EQN_TOK__MAX,
EQN_TOK_FUNC,
EQN_TOK_QUOTED,
EQN_TOK_SYM,
EQN_TOK_EOF
};
static const char *eqn_toks[EQN_TOK__MAX] = {
"dyad", /* EQN_TOK_DYAD */
"vec", /* EQN_TOK_VEC */
"under", /* EQN_TOK_UNDER */
"bar", /* EQN_TOK_BAR */
"tilde", /* EQN_TOK_TILDE */
"hat", /* EQN_TOK_HAT */
"dot", /* EQN_TOK_DOT */
"dotdot", /* EQN_TOK_DOTDOT */
"fwd", /* EQN_TOK_FWD * */
"back", /* EQN_TOK_BACK */
"down", /* EQN_TOK_DOWN */
"up", /* EQN_TOK_UP */
"fat", /* EQN_TOK_FAT */
"roman", /* EQN_TOK_ROMAN */
"italic", /* EQN_TOK_ITALIC */
"bold", /* EQN_TOK_BOLD */
"size", /* EQN_TOK_SIZE */
"sub", /* EQN_TOK_SUB */
"sup", /* EQN_TOK_SUP */
"sqrt", /* EQN_TOK_SQRT */
"over", /* EQN_TOK_OVER */
"from", /* EQN_TOK_FROM */
"to", /* EQN_TOK_TO */
"{", /* EQN_TOK_BRACE_OPEN */
"}", /* EQN_TOK_BRACE_CLOSE */
"gsize", /* EQN_TOK_GSIZE */
"gfont", /* EQN_TOK_GFONT */
"mark", /* EQN_TOK_MARK */
"lineup", /* EQN_TOK_LINEUP */
"left", /* EQN_TOK_LEFT */
"right", /* EQN_TOK_RIGHT */
"pile", /* EQN_TOK_PILE */
"lpile", /* EQN_TOK_LPILE */
"rpile", /* EQN_TOK_RPILE */
"cpile", /* EQN_TOK_CPILE */
"matrix", /* EQN_TOK_MATRIX */
"ccol", /* EQN_TOK_CCOL */
"lcol", /* EQN_TOK_LCOL */
"rcol", /* EQN_TOK_RCOL */
"delim", /* EQN_TOK_DELIM */
"define", /* EQN_TOK_DEFINE */
"tdefine", /* EQN_TOK_TDEFINE */
"ndefine", /* EQN_TOK_NDEFINE */
"undef", /* EQN_TOK_UNDEF */
"above", /* EQN_TOK_ABOVE */
};
static const char *const eqn_func[] = {
"acos", "acsc", "and", "arc", "asec", "asin", "atan",
"cos", "cosh", "coth", "csc", "det", "exp", "for",
"if", "lim", "ln", "log", "max", "min",
"sec", "sin", "sinh", "tan", "tanh", "Im", "Re",
};
enum eqn_symt {
EQNSYM_alpha = 0,
EQNSYM_beta,
EQNSYM_chi,
EQNSYM_delta,
EQNSYM_epsilon,
EQNSYM_eta,
EQNSYM_gamma,
EQNSYM_iota,
EQNSYM_kappa,
EQNSYM_lambda,
EQNSYM_mu,
EQNSYM_nu,
EQNSYM_omega,
EQNSYM_omicron,
EQNSYM_phi,
EQNSYM_pi,
EQNSYM_ps,
EQNSYM_rho,
EQNSYM_sigma,
EQNSYM_tau,
EQNSYM_theta,
EQNSYM_upsilon,
EQNSYM_xi,
EQNSYM_zeta,
EQNSYM_DELTA,
EQNSYM_GAMMA,
EQNSYM_LAMBDA,
EQNSYM_OMEGA,
EQNSYM_PHI,
EQNSYM_PI,
EQNSYM_PSI,
EQNSYM_SIGMA,
EQNSYM_THETA,
EQNSYM_UPSILON,
EQNSYM_XI,
EQNSYM_inter,
EQNSYM_union,
EQNSYM_prod,
EQNSYM_int,
EQNSYM_sum,
EQNSYM_grad,
EQNSYM_del,
EQNSYM_times,
EQNSYM_cdot,
EQNSYM_nothing,
EQNSYM_approx,
EQNSYM_prime,
EQNSYM_half,
EQNSYM_partial,
EQNSYM_inf,
EQNSYM_muchgreat,
EQNSYM_muchless,
EQNSYM_larrow,
EQNSYM_rarrow,
EQNSYM_pm,
EQNSYM_nequal,
EQNSYM_equiv,
EQNSYM_lessequal,
EQNSYM_moreequal,
EQNSYM_minus,
EQNSYM__MAX
};
struct eqnsym {
const char *str;
const char *sym;
};
static const struct eqnsym eqnsyms[EQNSYM__MAX] = {
{ "alpha", "*a" }, /* EQNSYM_alpha */
{ "beta", "*b" }, /* EQNSYM_beta */
{ "chi", "*x" }, /* EQNSYM_chi */
{ "delta", "*d" }, /* EQNSYM_delta */
{ "epsilon", "*e" }, /* EQNSYM_epsilon */
{ "eta", "*y" }, /* EQNSYM_eta */
{ "gamma", "*g" }, /* EQNSYM_gamma */
{ "iota", "*i" }, /* EQNSYM_iota */
{ "kappa", "*k" }, /* EQNSYM_kappa */
{ "lambda", "*l" }, /* EQNSYM_lambda */
{ "mu", "*m" }, /* EQNSYM_mu */
{ "nu", "*n" }, /* EQNSYM_nu */
{ "omega", "*w" }, /* EQNSYM_omega */
{ "omicron", "*o" }, /* EQNSYM_omicron */
{ "phi", "*f" }, /* EQNSYM_phi */
{ "pi", "*p" }, /* EQNSYM_pi */
{ "psi", "*q" }, /* EQNSYM_psi */
{ "rho", "*r" }, /* EQNSYM_rho */
{ "sigma", "*s" }, /* EQNSYM_sigma */
{ "tau", "*t" }, /* EQNSYM_tau */
{ "theta", "*h" }, /* EQNSYM_theta */
{ "upsilon", "*u" }, /* EQNSYM_upsilon */
{ "xi", "*c" }, /* EQNSYM_xi */
{ "zeta", "*z" }, /* EQNSYM_zeta */
{ "DELTA", "*D" }, /* EQNSYM_DELTA */
{ "GAMMA", "*G" }, /* EQNSYM_GAMMA */
{ "LAMBDA", "*L" }, /* EQNSYM_LAMBDA */
{ "OMEGA", "*W" }, /* EQNSYM_OMEGA */
{ "PHI", "*F" }, /* EQNSYM_PHI */
{ "PI", "*P" }, /* EQNSYM_PI */
{ "PSI", "*Q" }, /* EQNSYM_PSI */
{ "SIGMA", "*S" }, /* EQNSYM_SIGMA */
{ "THETA", "*H" }, /* EQNSYM_THETA */
{ "UPSILON", "*U" }, /* EQNSYM_UPSILON */
{ "XI", "*C" }, /* EQNSYM_XI */
{ "inter", "ca" }, /* EQNSYM_inter */
{ "union", "cu" }, /* EQNSYM_union */
{ "prod", "product" }, /* EQNSYM_prod */
{ "int", "integral" }, /* EQNSYM_int */
{ "sum", "sum" }, /* EQNSYM_sum */
{ "grad", "gr" }, /* EQNSYM_grad */
{ "del", "gr" }, /* EQNSYM_del */
{ "times", "mu" }, /* EQNSYM_times */
{ "cdot", "pc" }, /* EQNSYM_cdot */
{ "nothing", "&" }, /* EQNSYM_nothing */
{ "approx", "~~" }, /* EQNSYM_approx */
{ "prime", "fm" }, /* EQNSYM_prime */
{ "half", "12" }, /* EQNSYM_half */
{ "partial", "pd" }, /* EQNSYM_partial */
{ "inf", "if" }, /* EQNSYM_inf */
{ ">>", ">>" }, /* EQNSYM_muchgreat */
{ "<<", "<<" }, /* EQNSYM_muchless */
{ "<-", "<-" }, /* EQNSYM_larrow */
{ "->", "->" }, /* EQNSYM_rarrow */
{ "+-", "+-" }, /* EQNSYM_pm */
{ "!=", "!=" }, /* EQNSYM_nequal */
{ "==", "==" }, /* EQNSYM_equiv */
{ "<=", "<=" }, /* EQNSYM_lessequal */
{ ">=", ">=" }, /* EQNSYM_moreequal */
{ "-", "mi" }, /* EQNSYM_minus */
};
enum parse_mode {
MODE_QUOTED,
MODE_NOSUB,
MODE_SUB,
MODE_TOK
};
static struct eqn_box *eqn_box_alloc(struct eqn_node *, struct eqn_box *);
static struct eqn_box *eqn_box_makebinary(struct eqn_node *,
struct eqn_box *);
static void eqn_def(struct eqn_node *);
static struct eqn_def *eqn_def_find(struct eqn_node *);
static void eqn_delim(struct eqn_node *);
static enum eqn_tok eqn_next(struct eqn_node *, enum parse_mode);
static void eqn_undef(struct eqn_node *);
struct eqn_node *
eqn_alloc(struct mparse *parse)
{
struct eqn_node *ep;
ep = mandoc_calloc(1, sizeof(*ep));
ep->parse = parse;
ep->gsize = EQN_DEFSIZE;
return ep;
}
void
eqn_reset(struct eqn_node *ep)
{
free(ep->data);
ep->data = ep->start = ep->end = NULL;
ep->sz = ep->toksz = 0;
}
void
eqn_read(struct eqn_node *ep, const char *p)
{
char *cp;
if (ep->data == NULL) {
ep->sz = strlen(p);
ep->data = mandoc_strdup(p);
} else {
ep->sz = mandoc_asprintf(&cp, "%s %s", ep->data, p);
free(ep->data);
ep->data = cp;
}
ep->sz += 1;
}
/*
* Find the key "key" of the give size within our eqn-defined values.
*/
static struct eqn_def *
eqn_def_find(struct eqn_node *ep)
{
int i;
for (i = 0; i < (int)ep->defsz; i++)
if (ep->defs[i].keysz && STRNEQ(ep->defs[i].key,
ep->defs[i].keysz, ep->start, ep->toksz))
return &ep->defs[i];
return NULL;
}
/*
* Parse a token from the input text. The modes are:
* MODE_QUOTED: Use *ep->start as the delimiter; the token ends
* before its next occurence. Do not interpret the token in any
* way and return EQN_TOK_QUOTED. All other modes behave like
* MODE_QUOTED when *ep->start is '"'.
* MODE_NOSUB: If *ep->start is a curly brace, the token ends after it;
* otherwise, it ends before the next whitespace or brace.
* Do not interpret the token and return EQN_TOK__MAX.
* MODE_SUB: Like MODE_NOSUB, but try to interpret the token as an
* alias created with define. If it is an alias, replace it with
* its string value and reparse.
* MODE_TOK: Like MODE_SUB, but also check the token against the list
* of tokens, and if there is a match, return that token. Otherwise,
* if the token matches a symbol, return EQN_TOK_SYM; if it matches
* a function name, EQN_TOK_FUNC, or else EQN_TOK__MAX. Except for
* a token match, *ep->start is set to an allocated string that the
* caller is expected to free.
* All modes skip whitespace following the end of the token.
*/
static enum eqn_tok
eqn_next(struct eqn_node *ep, enum parse_mode mode)
{
static int last_len, lim;
struct eqn_def *def;
size_t start;
int diff, i, quoted;
enum eqn_tok tok;
/*
* Reset the recursion counter after advancing
* beyond the end of the previous substitution.
*/
if (ep->end - ep->data >= last_len)
lim = 0;
ep->start = ep->end;
quoted = mode == MODE_QUOTED;
for (;;) {
switch (*ep->start) {
case '\0':
ep->toksz = 0;
return EQN_TOK_EOF;
case '"':
quoted = 1;
break;
default:
break;
}
if (quoted) {
ep->end = strchr(ep->start + 1, *ep->start);
ep->start++; /* Skip opening quote. */
if (ep->end == NULL) {
mandoc_msg(MANDOCERR_ARG_QUOTE, ep->parse,
ep->node->line, ep->node->pos, NULL);
ep->end = strchr(ep->start, '\0');
}
} else {
ep->end = ep->start + 1;
if (*ep->start != '{' && *ep->start != '}')
ep->end += strcspn(ep->end, " ^~\"{}\t");
}
ep->toksz = ep->end - ep->start;
if (quoted && *ep->end != '\0')
ep->end++; /* Skip closing quote. */
while (*ep->end != '\0' && strchr(" \t^~", *ep->end) != NULL)
ep->end++;
if (quoted) /* Cannot return, may have to strndup. */
break;
if (mode == MODE_NOSUB)
return EQN_TOK__MAX;
if ((def = eqn_def_find(ep)) == NULL)
break;
if (++lim > EQN_NEST_MAX) {
mandoc_msg(MANDOCERR_ROFFLOOP, ep->parse,
ep->node->line, ep->node->pos, NULL);
return EQN_TOK_EOF;
}
/* Replace a defined name with its string value. */
if ((diff = def->valsz - ep->toksz) > 0) {
start = ep->start - ep->data;
ep->sz += diff;
ep->data = mandoc_realloc(ep->data, ep->sz + 1);
ep->start = ep->data + start;
}
if (diff)
memmove(ep->start + def->valsz, ep->start + ep->toksz,
strlen(ep->start + ep->toksz) + 1);
memcpy(ep->start, def->val, def->valsz);
last_len = ep->start - ep->data + def->valsz;
}
if (mode != MODE_TOK)
return quoted ? EQN_TOK_QUOTED : EQN_TOK__MAX;
if (quoted) {
ep->start = mandoc_strndup(ep->start, ep->toksz);
return EQN_TOK_QUOTED;
}
for (tok = 0; tok < EQN_TOK__MAX; tok++)
if (STRNEQ(ep->start, ep->toksz,
eqn_toks[tok], strlen(eqn_toks[tok])))
return tok;
for (i = 0; i < EQNSYM__MAX; i++) {
if (STRNEQ(ep->start, ep->toksz,
eqnsyms[i].str, strlen(eqnsyms[i].str))) {
mandoc_asprintf(&ep->start,
"\\[%s]", eqnsyms[i].sym);
return EQN_TOK_SYM;
}
}
ep->start = mandoc_strndup(ep->start, ep->toksz);
for (i = 0; i < (int)(sizeof(eqn_func)/sizeof(*eqn_func)); i++)
if (STRNEQ(ep->start, ep->toksz,
eqn_func[i], strlen(eqn_func[i])))
return EQN_TOK_FUNC;
return EQN_TOK__MAX;
}
void
eqn_box_free(struct eqn_box *bp)
{
if (bp->first)
eqn_box_free(bp->first);
if (bp->next)
eqn_box_free(bp->next);
free(bp->text);
free(bp->left);
free(bp->right);
free(bp->top);
free(bp->bottom);
free(bp);
}
/*
* Allocate a box as the last child of the parent node.
*/
static struct eqn_box *
eqn_box_alloc(struct eqn_node *ep, struct eqn_box *parent)
{
struct eqn_box *bp;
bp = mandoc_calloc(1, sizeof(struct eqn_box));
bp->parent = parent;
bp->parent->args++;
bp->expectargs = UINT_MAX;
bp->font = bp->parent->font;
bp->size = ep->gsize;
if (NULL != parent->first) {
parent->last->next = bp;
bp->prev = parent->last;
} else
parent->first = bp;
parent->last = bp;
return bp;
}
/*
* Reparent the current last node (of the current parent) under a new
* EQN_SUBEXPR as the first element.
* Then return the new parent.
* The new EQN_SUBEXPR will have a two-child limit.
*/
static struct eqn_box *
eqn_box_makebinary(struct eqn_node *ep, struct eqn_box *parent)
{
struct eqn_box *b, *newb;
assert(NULL != parent->last);
b = parent->last;
if (parent->last == parent->first)
parent->first = NULL;
parent->args--;
parent->last = b->prev;
b->prev = NULL;
newb = eqn_box_alloc(ep, parent);
newb->type = EQN_SUBEXPR;
newb->expectargs = 2;
newb->args = 1;
newb->first = newb->last = b;
newb->first->next = NULL;
b->parent = newb;
return newb;
}
/*
* Parse the "delim" control statement.
*/
static void
eqn_delim(struct eqn_node *ep)
{
if (ep->end[0] == '\0' || ep->end[1] == '\0') {
mandoc_msg(MANDOCERR_REQ_EMPTY, ep->parse,
ep->node->line, ep->node->pos, "delim");
if (ep->end[0] != '\0')
ep->end++;
} else if (strncmp(ep->end, "off", 3) == 0) {
ep->delim = 0;
ep->end += 3;
} else if (strncmp(ep->end, "on", 2) == 0) {
if (ep->odelim && ep->cdelim)
ep->delim = 1;
ep->end += 2;
} else {
ep->odelim = *ep->end++;
ep->cdelim = *ep->end++;
ep->delim = 1;
}
}
/*
* Undefine a previously-defined string.
*/
static void
eqn_undef(struct eqn_node *ep)
{
struct eqn_def *def;
if (eqn_next(ep, MODE_NOSUB) == EQN_TOK_EOF) {
mandoc_msg(MANDOCERR_REQ_EMPTY, ep->parse,
ep->node->line, ep->node->pos, "undef");
return;
}
if ((def = eqn_def_find(ep)) == NULL)
return;
free(def->key);
free(def->val);
def->key = def->val = NULL;
def->keysz = def->valsz = 0;
}
static void
eqn_def(struct eqn_node *ep)
{
struct eqn_def *def;
int i;
if (eqn_next(ep, MODE_NOSUB) == EQN_TOK_EOF) {
mandoc_msg(MANDOCERR_REQ_EMPTY, ep->parse,
ep->node->line, ep->node->pos, "define");
return;
}
/*
* Search for a key that already exists.
* Create a new key if none is found.
*/
if ((def = eqn_def_find(ep)) == NULL) {
/* Find holes in string array. */
for (i = 0; i < (int)ep->defsz; i++)
if (0 == ep->defs[i].keysz)
break;
if (i == (int)ep->defsz) {
ep->defsz++;
ep->defs = mandoc_reallocarray(ep->defs,
ep->defsz, sizeof(struct eqn_def));
ep->defs[i].key = ep->defs[i].val = NULL;
}
def = ep->defs + i;
free(def->key);
def->key = mandoc_strndup(ep->start, ep->toksz);
def->keysz = ep->toksz;
}
if (eqn_next(ep, MODE_QUOTED) == EQN_TOK_EOF) {
mandoc_vmsg(MANDOCERR_REQ_EMPTY, ep->parse,
ep->node->line, ep->node->pos, "define %s", def->key);
free(def->key);
free(def->val);
def->key = def->val = NULL;
def->keysz = def->valsz = 0;
return;
}
free(def->val);
def->val = mandoc_strndup(ep->start, ep->toksz);
def->valsz = ep->toksz;
}
void
eqn_parse(struct eqn_node *ep)
{
struct eqn_box *cur, *nbox, *parent, *split;
const char *cp, *cpn;
char *p;
enum eqn_tok tok;
enum { CCL_LET, CCL_DIG, CCL_PUN } ccl, ccln;
int size;
parent = ep->node->eqn;
assert(parent != NULL);
/*
* Empty equation.
* Do not add it to the high-level syntax tree.
*/
if (ep->data == NULL)
return;
ep->start = ep->end = ep->data + strspn(ep->data, " ^~");
next_tok:
tok = eqn_next(ep, MODE_TOK);
switch (tok) {
case EQN_TOK_UNDEF:
eqn_undef(ep);
break;
case EQN_TOK_NDEFINE:
case EQN_TOK_DEFINE:
eqn_def(ep);
break;
case EQN_TOK_TDEFINE:
if (eqn_next(ep, MODE_NOSUB) == EQN_TOK_EOF ||
eqn_next(ep, MODE_QUOTED) == EQN_TOK_EOF)
mandoc_msg(MANDOCERR_REQ_EMPTY, ep->parse,
ep->node->line, ep->node->pos, "tdefine");
break;
case EQN_TOK_DELIM:
eqn_delim(ep);
break;
case EQN_TOK_GFONT:
if (eqn_next(ep, MODE_SUB) == EQN_TOK_EOF)
mandoc_msg(MANDOCERR_REQ_EMPTY, ep->parse,
ep->node->line, ep->node->pos, eqn_toks[tok]);
break;
case EQN_TOK_MARK:
case EQN_TOK_LINEUP:
/* Ignore these. */
break;
case EQN_TOK_DYAD:
case EQN_TOK_VEC:
case EQN_TOK_UNDER:
case EQN_TOK_BAR:
case EQN_TOK_TILDE:
case EQN_TOK_HAT:
case EQN_TOK_DOT:
case EQN_TOK_DOTDOT:
if (parent->last == NULL) {
mandoc_msg(MANDOCERR_EQN_NOBOX, ep->parse,
ep->node->line, ep->node->pos, eqn_toks[tok]);
cur = eqn_box_alloc(ep, parent);
cur->type = EQN_TEXT;
cur->text = mandoc_strdup("");
}
parent = eqn_box_makebinary(ep, parent);
parent->type = EQN_LIST;
parent->expectargs = 1;
parent->font = EQNFONT_ROMAN;
switch (tok) {
case EQN_TOK_DOTDOT:
parent->top = mandoc_strdup("\\[ad]");
break;
case EQN_TOK_VEC:
parent->top = mandoc_strdup("\\[->]");
break;
case EQN_TOK_DYAD:
parent->top = mandoc_strdup("\\[<>]");
break;
case EQN_TOK_TILDE:
parent->top = mandoc_strdup("\\[a~]");
break;
case EQN_TOK_UNDER:
parent->bottom = mandoc_strdup("\\[ul]");
break;
case EQN_TOK_BAR:
parent->top = mandoc_strdup("\\[rn]");
break;
case EQN_TOK_DOT:
parent->top = mandoc_strdup("\\[a.]");
break;
case EQN_TOK_HAT:
parent->top = mandoc_strdup("\\[ha]");
break;
default:
abort();
}
parent = parent->parent;
break;
case EQN_TOK_FWD:
case EQN_TOK_BACK:
case EQN_TOK_DOWN:
case EQN_TOK_UP:
if (eqn_next(ep, MODE_SUB) == EQN_TOK_EOF)
mandoc_msg(MANDOCERR_REQ_EMPTY, ep->parse,
ep->node->line, ep->node->pos, eqn_toks[tok]);
break;
case EQN_TOK_FAT:
case EQN_TOK_ROMAN:
case EQN_TOK_ITALIC:
case EQN_TOK_BOLD:
while (parent->args == parent->expectargs)
parent = parent->parent;
/*
* These values apply to the next word or sequence of
* words; thus, we mark that we'll have a child with
* exactly one of those.
*/
parent = eqn_box_alloc(ep, parent);
parent->type = EQN_LIST;
parent->expectargs = 1;
switch (tok) {
case EQN_TOK_FAT:
parent->font = EQNFONT_FAT;
break;
case EQN_TOK_ROMAN:
parent->font = EQNFONT_ROMAN;
break;
case EQN_TOK_ITALIC:
parent->font = EQNFONT_ITALIC;
break;
case EQN_TOK_BOLD:
parent->font = EQNFONT_BOLD;
break;
default:
abort();
}
break;
case EQN_TOK_SIZE:
case EQN_TOK_GSIZE:
/* Accept two values: integral size and a single. */
if (eqn_next(ep, MODE_SUB) == EQN_TOK_EOF) {
mandoc_msg(MANDOCERR_REQ_EMPTY, ep->parse,
ep->node->line, ep->node->pos, eqn_toks[tok]);
break;
}
size = mandoc_strntoi(ep->start, ep->toksz, 10);
if (-1 == size) {
mandoc_msg(MANDOCERR_IT_NONUM, ep->parse,
ep->node->line, ep->node->pos, eqn_toks[tok]);
break;
}
if (EQN_TOK_GSIZE == tok) {
ep->gsize = size;
break;
}
while (parent->args == parent->expectargs)
parent = parent->parent;
parent = eqn_box_alloc(ep, parent);
parent->type = EQN_LIST;
parent->expectargs = 1;
parent->size = size;
break;
case EQN_TOK_FROM:
case EQN_TOK_TO:
case EQN_TOK_SUB:
case EQN_TOK_SUP:
/*
* We have a left-right-associative expression.
* Repivot under a positional node, open a child scope
* and keep on reading.
*/
if (parent->last == NULL) {
mandoc_msg(MANDOCERR_EQN_NOBOX, ep->parse,
ep->node->line, ep->node->pos, eqn_toks[tok]);
cur = eqn_box_alloc(ep, parent);
cur->type = EQN_TEXT;
cur->text = mandoc_strdup("");
}
while (parent->expectargs == 1 && parent->args == 1)
parent = parent->parent;
if (tok == EQN_TOK_FROM || tok == EQN_TOK_TO) {
for (cur = parent; cur != NULL; cur = cur->parent)
if (cur->pos == EQNPOS_SUB ||
cur->pos == EQNPOS_SUP ||
cur->pos == EQNPOS_SUBSUP ||
cur->pos == EQNPOS_SQRT ||
cur->pos == EQNPOS_OVER)
break;
if (cur != NULL)
parent = cur->parent;
}
if (tok == EQN_TOK_SUP && parent->pos == EQNPOS_SUB) {
parent->expectargs = 3;
parent->pos = EQNPOS_SUBSUP;
break;
}
if (tok == EQN_TOK_TO && parent->pos == EQNPOS_FROM) {
parent->expectargs = 3;
parent->pos = EQNPOS_FROMTO;
break;
}
parent = eqn_box_makebinary(ep, parent);
switch (tok) {
case EQN_TOK_FROM:
parent->pos = EQNPOS_FROM;
break;
case EQN_TOK_TO:
parent->pos = EQNPOS_TO;
break;
case EQN_TOK_SUP:
parent->pos = EQNPOS_SUP;
break;
case EQN_TOK_SUB:
parent->pos = EQNPOS_SUB;
break;
default:
abort();
}
break;
case EQN_TOK_SQRT:
while (parent->args == parent->expectargs)
parent = parent->parent;
/*
* Accept a left-right-associative set of arguments just
* like sub and sup and friends but without rebalancing
* under a pivot.
*/
parent = eqn_box_alloc(ep, parent);
parent->type = EQN_SUBEXPR;
parent->pos = EQNPOS_SQRT;
parent->expectargs = 1;
break;
case EQN_TOK_OVER:
/*
* We have a right-left-associative fraction.
* Close out anything that's currently open, then
* rebalance and continue reading.
*/
if (parent->last == NULL) {
mandoc_msg(MANDOCERR_EQN_NOBOX, ep->parse,
ep->node->line, ep->node->pos, eqn_toks[tok]);
cur = eqn_box_alloc(ep, parent);
cur->type = EQN_TEXT;
cur->text = mandoc_strdup("");
}
while (parent->args == parent->expectargs)
parent = parent->parent;
while (EQN_SUBEXPR == parent->type)
parent = parent->parent;
parent = eqn_box_makebinary(ep, parent);
parent->pos = EQNPOS_OVER;
break;
case EQN_TOK_RIGHT:
case EQN_TOK_BRACE_CLOSE:
/*
* Close out the existing brace.
* FIXME: this is a shitty sentinel: we should really
* have a native EQN_BRACE type or whatnot.
*/
for (cur = parent; cur != NULL; cur = cur->parent)
if (cur->type == EQN_LIST &&
cur->expectargs > 1 &&
(tok == EQN_TOK_BRACE_CLOSE ||
cur->left != NULL))
break;
if (cur == NULL) {
mandoc_msg(MANDOCERR_BLK_NOTOPEN, ep->parse,
ep->node->line, ep->node->pos, eqn_toks[tok]);
break;
}
parent = cur;
if (EQN_TOK_RIGHT == tok) {
if (eqn_next(ep, MODE_SUB) == EQN_TOK_EOF) {
mandoc_msg(MANDOCERR_REQ_EMPTY,
ep->parse, ep->node->line,
ep->node->pos, eqn_toks[tok]);
break;
}
/* Handling depends on right/left. */
if (STRNEQ(ep->start, ep->toksz, "ceiling", 7))
parent->right = mandoc_strdup("\\[rc]");
else if (STRNEQ(ep->start, ep->toksz, "floor", 5))
parent->right = mandoc_strdup("\\[rf]");
else
parent->right =
mandoc_strndup(ep->start, ep->toksz);
}
parent = parent->parent;
if (tok == EQN_TOK_BRACE_CLOSE &&
(parent->type == EQN_PILE ||
parent->type == EQN_MATRIX))
parent = parent->parent;
/* Close out any "singleton" lists. */
while (parent->type == EQN_LIST &&
parent->expectargs == 1 &&
parent->args == 1)
parent = parent->parent;
break;
case EQN_TOK_BRACE_OPEN:
case EQN_TOK_LEFT:
/*
* If we already have something in the stack and we're
* in an expression, then rewind til we're not any more
* (just like with the text node).
*/
while (parent->args == parent->expectargs)
parent = parent->parent;
if (EQN_TOK_LEFT == tok &&
eqn_next(ep, MODE_SUB) == EQN_TOK_EOF) {
mandoc_msg(MANDOCERR_REQ_EMPTY, ep->parse,
ep->node->line, ep->node->pos, eqn_toks[tok]);
break;
}
parent = eqn_box_alloc(ep, parent);
parent->type = EQN_LIST;
if (EQN_TOK_LEFT == tok) {
if (STRNEQ(ep->start, ep->toksz, "ceiling", 7))
parent->left = mandoc_strdup("\\[lc]");
else if (STRNEQ(ep->start, ep->toksz, "floor", 5))
parent->left = mandoc_strdup("\\[lf]");
else
parent->left =
mandoc_strndup(ep->start, ep->toksz);
}
break;
case EQN_TOK_PILE:
case EQN_TOK_LPILE:
case EQN_TOK_RPILE:
case EQN_TOK_CPILE:
case EQN_TOK_CCOL:
case EQN_TOK_LCOL:
case EQN_TOK_RCOL:
while (parent->args == parent->expectargs)
parent = parent->parent;
parent = eqn_box_alloc(ep, parent);
parent->type = EQN_PILE;
parent->expectargs = 1;
break;
case EQN_TOK_ABOVE:
for (cur = parent; cur != NULL; cur = cur->parent)
if (cur->type == EQN_PILE)
break;
if (cur == NULL) {
mandoc_msg(MANDOCERR_IT_STRAY, ep->parse,
ep->node->line, ep->node->pos, eqn_toks[tok]);
break;
}
parent = eqn_box_alloc(ep, cur);
parent->type = EQN_LIST;
break;
case EQN_TOK_MATRIX:
while (parent->args == parent->expectargs)
parent = parent->parent;
parent = eqn_box_alloc(ep, parent);
parent->type = EQN_MATRIX;
parent->expectargs = 1;
break;
case EQN_TOK_EOF:
return;
case EQN_TOK__MAX:
case EQN_TOK_FUNC:
case EQN_TOK_QUOTED:
case EQN_TOK_SYM:
p = ep->start;
assert(p != NULL);
/*
* If we already have something in the stack and we're
* in an expression, then rewind til we're not any more.
*/
while (parent->args == parent->expectargs)
parent = parent->parent;
cur = eqn_box_alloc(ep, parent);
cur->type = EQN_TEXT;
cur->text = p;
switch (tok) {
case EQN_TOK_FUNC:
cur->font = EQNFONT_ROMAN;
break;
case EQN_TOK_QUOTED:
if (cur->font == EQNFONT_NONE)
cur->font = EQNFONT_ITALIC;
break;
case EQN_TOK_SYM:
break;
default:
if (cur->font != EQNFONT_NONE || *p == '\0')
break;
cpn = p - 1;
ccln = CCL_LET;
split = NULL;
for (;;) {
/* Advance to next character. */
cp = cpn++;
ccl = ccln;
ccln = isalpha((unsigned char)*cpn) ? CCL_LET :
isdigit((unsigned char)*cpn) ||
(*cpn == '.' && (ccl == CCL_DIG ||
isdigit((unsigned char)cpn[1]))) ?
CCL_DIG : CCL_PUN;
/* No boundary before first character. */
if (cp < p)
continue;
cur->font = ccl == CCL_LET ?
EQNFONT_ITALIC : EQNFONT_ROMAN;
if (*cp == '\\')
mandoc_escape(&cpn, NULL, NULL);
/* No boundary after last character. */
if (*cpn == '\0')
break;
if (ccln == ccl && *cp != ',' && *cpn != ',')
continue;
/* Boundary found, split the text. */
if (parent->args == parent->expectargs) {
/* Remove the text from the tree. */
if (cur->prev == NULL)
parent->first = cur->next;
else
cur->prev->next = NULL;
parent->last = cur->prev;
parent->args--;
/* Set up a list instead. */
split = eqn_box_alloc(ep, parent);
split->type = EQN_LIST;
/* Insert the word into the list. */
split->first = split->last = cur;
cur->parent = split;
cur->prev = NULL;
parent = split;
}
/* Append a new text box. */
nbox = eqn_box_alloc(ep, parent);
nbox->type = EQN_TEXT;
nbox->text = mandoc_strdup(cpn);
/* Truncate the old box. */
p = mandoc_strndup(cur->text,
cpn - cur->text);
free(cur->text);
cur->text = p;
/* Setup to process the new box. */
cur = nbox;
p = nbox->text;
cpn = p - 1;
ccln = CCL_LET;
}
if (split != NULL)
parent = split->parent;
break;
}
break;
default:
abort();
}
goto next_tok;
}
void
eqn_free(struct eqn_node *p)
{
int i;
for (i = 0; i < (int)p->defsz; i++) {
free(p->defs[i].key);
free(p->defs[i].val);
}
free(p->data);
free(p->defs);
free(p);
}
mandoc-1.14.3/eqn_html.c 0100644 0002007 0000011 00000013575 13141336266 0014444 0 ustar 00schwarze wsrc /* $Id: eqn_html.c,v 1.17 2017/07/14 13:32:35 schwarze Exp $ */
/*
* Copyright (c) 2011, 2014 Kristaps Dzonsons
* Copyright (c) 2017 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#include "config.h"
#include
#include
#include
#include
#include
#include
#include "mandoc.h"
#include "out.h"
#include "html.h"
static void
eqn_box(struct html *p, const struct eqn_box *bp)
{
struct tag *post, *row, *cell, *t;
const struct eqn_box *child, *parent;
const char *cp;
size_t i, j, rows;
enum htmltag tag;
enum eqn_fontt font;
if (NULL == bp)
return;
post = NULL;
/*
* Special handling for a matrix, which is presented to us in
* column order, but must be printed in row-order.
*/
if (EQN_MATRIX == bp->type) {
if (NULL == bp->first)
goto out;
if (bp->first->type != EQN_LIST ||
bp->first->expectargs == 1) {
eqn_box(p, bp->first);
goto out;
}
if (NULL == (parent = bp->first->first))
goto out;
/* Estimate the number of rows, first. */
if (NULL == (child = parent->first))
goto out;
for (rows = 0; NULL != child; rows++)
child = child->next;
/* Print row-by-row. */
post = print_otag(p, TAG_MTABLE, "");
for (i = 0; i < rows; i++) {
parent = bp->first->first;
row = print_otag(p, TAG_MTR, "");
while (NULL != parent) {
child = parent->first;
for (j = 0; j < i; j++) {
if (NULL == child)
break;
child = child->next;
}
cell = print_otag(p, TAG_MTD, "");
/*
* If we have no data for this
* particular cell, then print a
* placeholder and continue--don't puke.
*/
if (NULL != child)
eqn_box(p, child->first);
print_tagq(p, cell);
parent = parent->next;
}
print_tagq(p, row);
}
goto out;
}
switch (bp->pos) {
case EQNPOS_TO:
post = print_otag(p, TAG_MOVER, "");
break;
case EQNPOS_SUP:
post = print_otag(p, TAG_MSUP, "");
break;
case EQNPOS_FROM:
post = print_otag(p, TAG_MUNDER, "");
break;
case EQNPOS_SUB:
post = print_otag(p, TAG_MSUB, "");
break;
case EQNPOS_OVER:
post = print_otag(p, TAG_MFRAC, "");
break;
case EQNPOS_FROMTO:
post = print_otag(p, TAG_MUNDEROVER, "");
break;
case EQNPOS_SUBSUP:
post = print_otag(p, TAG_MSUBSUP, "");
break;
case EQNPOS_SQRT:
post = print_otag(p, TAG_MSQRT, "");
break;
default:
break;
}
if (bp->top || bp->bottom) {
assert(NULL == post);
if (bp->top && NULL == bp->bottom)
post = print_otag(p, TAG_MOVER, "");
else if (bp->top && bp->bottom)
post = print_otag(p, TAG_MUNDEROVER, "");
else if (bp->bottom)
post = print_otag(p, TAG_MUNDER, "");
}
if (EQN_PILE == bp->type) {
assert(NULL == post);
if (bp->first != NULL &&
bp->first->type == EQN_LIST &&
bp->first->expectargs > 1)
post = print_otag(p, TAG_MTABLE, "");
} else if (bp->type == EQN_LIST && bp->expectargs > 1 &&
bp->parent && bp->parent->type == EQN_PILE) {
assert(NULL == post);
post = print_otag(p, TAG_MTR, "");
print_otag(p, TAG_MTD, "");
}
if (bp->text != NULL) {
assert(post == NULL);
tag = TAG_MI;
cp = bp->text;
if (isdigit((unsigned char)cp[0]) ||
(cp[0] == '.' && isdigit((unsigned char)cp[1]))) {
tag = TAG_MN;
while (*++cp != '\0') {
if (*cp != '.' &&
isdigit((unsigned char)*cp) == 0) {
tag = TAG_MI;
break;
}
}
} else if (*cp != '\0' && isalpha((unsigned char)*cp) == 0) {
tag = TAG_MO;
while (*cp != '\0') {
if (cp[0] == '\\' && cp[1] != '\0') {
cp++;
mandoc_escape(&cp, NULL, NULL);
} else if (isalnum((unsigned char)*cp)) {
tag = TAG_MI;
break;
} else
cp++;
}
}
font = bp->font;
if (bp->text[0] != '\0' &&
(((tag == TAG_MN || tag == TAG_MO) &&
font == EQNFONT_ROMAN) ||
(tag == TAG_MI && font == (bp->text[1] == '\0' ?
EQNFONT_ITALIC : EQNFONT_ROMAN))))
font = EQNFONT_NONE;
switch (font) {
case EQNFONT_NONE:
post = print_otag(p, tag, "");
break;
case EQNFONT_ROMAN:
post = print_otag(p, tag, "?", "fontstyle", "normal");
break;
case EQNFONT_BOLD:
case EQNFONT_FAT:
post = print_otag(p, tag, "?", "fontweight", "bold");
break;
case EQNFONT_ITALIC:
post = print_otag(p, tag, "?", "fontstyle", "italic");
break;
default:
abort();
}
print_text(p, bp->text);
} else if (NULL == post) {
if (NULL != bp->left || NULL != bp->right)
post = print_otag(p, TAG_MFENCED, "??",
"open", bp->left == NULL ? "" : bp->left,
"close", bp->right == NULL ? "" : bp->right);
if (NULL == post)
post = print_otag(p, TAG_MROW, "");
else
print_otag(p, TAG_MROW, "");
}
eqn_box(p, bp->first);
out:
if (NULL != bp->bottom) {
t = print_otag(p, TAG_MO, "");
print_text(p, bp->bottom);
print_tagq(p, t);
}
if (NULL != bp->top) {
t = print_otag(p, TAG_MO, "");
print_text(p, bp->top);
print_tagq(p, t);
}
if (NULL != post)
print_tagq(p, post);
eqn_box(p, bp->next);
}
void
print_eqn(struct html *p, const struct eqn_box *bp)
{
struct tag *t;
if (bp->first == NULL)
return;
t = print_otag(p, TAG_MATH, "c", "eqn");
p->flags |= HTML_NONOSPACE;
eqn_box(p, bp);
p->flags &= ~HTML_NONOSPACE;
print_tagq(p, t);
}
mandoc-1.14.3/eqn_term.c 0100644 0002007 0000011 00000010225 13141336266 0014434 0 ustar 00schwarze wsrc /* $Id: eqn_term.c,v 1.13 2017/07/08 14:51:04 schwarze Exp $ */
/*
* Copyright (c) 2011 Kristaps Dzonsons
* Copyright (c) 2014, 2015, 2017 Ingo Schwarze
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
#include "config.h"
#include
#include