From 51b80f5088ac30124cca09023af7fcccc4b63653 Mon Sep 17 00:00:00 2001 From: Kristaps Dzonsons Date: Tue, 22 Mar 2011 10:02:50 +0000 Subject: Step 3: consolidate manuals. The parse functions in mdoc.h, roff.h, and man.h are now part of libmandoc.h, so remove these from their respective manuals (they're no longer public-facing and we don't need a libmandoc.3 (yet?)). Before that, move the juicy data (parse tree syntax) into new-born mandoc.3. Peck around in Makefile and index.sgml to reflect reality. --- roff.3 | 177 ----------------------------------------------------------------- 1 file changed, 177 deletions(-) delete mode 100644 roff.3 (limited to 'roff.3') diff --git a/roff.3 b/roff.3 deleted file mode 100644 index 7d8bff5c..00000000 --- a/roff.3 +++ /dev/null @@ -1,177 +0,0 @@ -.\" $Id: roff.3,v 1.10 2011/01/01 16:18:39 kristaps Exp $ -.\" -.\" Copyright (c) 2010 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. -.\" -.Dd $Mdocdate: January 1 2011 $ -.Dt ROFF 3 -.Os -.Sh NAME -.Nm roff , -.Nm roff_alloc , -.Nm roff_endparse , -.Nm roff_free , -.Nm roff_parseln , -.Nm roff_reset , -.Nm roff_span -.Nd roff macro compiler library -.Sh SYNOPSIS -.In mandoc.h -.In roff.h -.Ft "struct roff *" -.Fo roff_alloc -.Fa "struct regset *regs" -.Fa "void *data" -.Fa "mandocmsg msgs" -.Fc -.Ft void -.Fn roff_endparse "struct roff *roff" -.Ft void -.Fn roff_free "struct roff *roff" -.Ft "enum rofferr" -.Fo roff_parseln -.Fa "struct roff *roff" -.Fa "int line" -.Fa "char **bufp" -.Fa "size_t *bufsz" -.Fa "int pos" -.Fa "int *offs" -.Fc -.Ft void -.Fn roff_reset "struct roff *roff" -.Ft "const struct tbl_span *" -.Fn roff_span "const struct roff *roff" -.Sh DESCRIPTION -The -.Nm -library processes lines of -.Xr roff 7 -input. -.Pp -In general, applications initiate a parsing sequence with -.Fn roff_alloc , -parse each line in a document with -.Fn roff_parseln , -close the parsing session with -.Fn roff_endparse , -and finally free all allocated memory with -.Fn roff_free . -The -.Fn roff_reset -function may be used in order to reset the parser for another input -sequence. -.Pp -The -.Fn roff_parseln -function should be invoked before passing a line into the -.Xr mdoc 3 -or -.Xr man 3 -libraries. -.Pp -See the -.Sx EXAMPLES -section for a full example. -.Sh REFERENCE -This section further defines the -.Sx Types -and -.Sx Functions -available to programmers. -.Ss Types -Functions (see -.Sx Functions ) -may use the following types: -.Bl -ohang -.It Vt "enum rofferr" -Instructions for further processing to the caller of -.Fn roff_parseln . -.It Vt struct roff -An opaque type defined in -.Pa roff.c . -Its values are only used privately within the library. -.It Vt mandocmsg -A function callback type defined in -.Pa mandoc.h . -.El -.Ss Functions -Function descriptions follow: -.Bl -ohang -.It Fn roff_alloc -Allocates a parsing structure. -The -.Fa data -pointer is passed to -.Fa msgs . -Returns NULL on failure. -If non-NULL, the pointer must be freed with -.Fn roff_free . -.It Fn roff_reset -Reset the parser for another parse routine. -After its use, -.Fn roff_parseln -behaves as if invoked for the first time. -.It Fn roff_free -Free all resources of a parser. -The pointer is no longer valid after invocation. -.It Fn roff_parseln -Parse a nil-terminated line of input. -The character array -.Fa bufp -may be modified or reallocated within this function. -In the latter case, -.Fa bufsz -will be modified accordingly. -The -.Fa offs -pointer will be modified if the line start during subsequent processing -of the line is not at the zeroth index. -This line should not contain the trailing newline. -Returns 0 on failure, 1 on success. -.It Fn roff_endparse -Signals that the parse is complete. -.It Fn roff_span -If -.Fn roff_parseln -returned -.Va ROFF_TBL , -return the last parsed table row. -Returns NULL otherwise. -.El -.Sh EXAMPLES -See -.Pa main.c -in the source distribution for an example of usage. -.Sh SEE ALSO -.Xr mandoc 1 , -.Xr man 3 , -.Xr mdoc 3 , -.Xr roff 7 -.Sh AUTHORS -The -.Nm -library was written by -.An Kristaps Dzonsons Aq kristaps@bsd.lv . -.Sh BUGS -The implementation of user-defined strings needs improvement: -.Bl -dash -.It -String values are taken literally and are not interpreted. -.It -Parsing of quoted strings is incomplete. -.It -The stings are stored internally using a singly linked list, -which is fine for small numbers of strings, -but ineffient when handling many strings. -.El -- cgit v1.2.3-56-ge451