gitweb.dragonflybsd.org Git - dragonfly.git/blame_incremental

... / ...

Commit	Line	Data
	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
	2	<HTML>
	3	<HEAD>
	4	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
	5	<LINK REL="stylesheet" HREF="index.css" TYPE="text/css" MEDIA="all">
	6	<TITLE>mdocml \| mdoc macro compiler</TITLE>
	7	</HEAD>
	8	<BODY>
	9	<P CLASS="head">
	10	<B>mdocml</B> – mdoc macro compiler
	11	</P>
	12	<H1>
	13	<A NAME="description">Description</A>
	14	</H1>
	15	<P>
	16	<SPAN CLASS="nm">mdocml</SPAN> is a suite of tools compiling <I><A HREF="mdoc.7.html">mdoc</A></I>, the roff macro
	17	package of choice for BSD manual pages, and <I><A HREF="man.7.html">man</A></I>, the predominant historical package for
	18	UNIX manuals. The mission of <SPAN CLASS="nm">mdocml</SPAN> is to deprecate <A
	19	HREF="http://www.gnu.org/software/groff/" CLASS="external">groff</A>, the GNU troff implementation, for displaying <I>mdoc</I>
	20	pages whilst providing token support for <I>man</I>.
	21	</P>
	22	<P>
	23	Why? groff amounts to over 5 MB of source code, most of which is C++ and all of which is GPL. It runs slowly, produces
	24	uncertain output, and varies in operation from system to system. mdocml strives to fix this (respectively small, C, <A
	25	CLASS="external" HREF="http://www.isc.org/software/license">ISC</A>-licensed, fast and regular).
	26	</P>
	27	<P>
	28	<SPAN CLASS="nm">mdocml</SPAN> consists of the <A HREF="mandoc.3.html">libmandoc</A> validating compiler and <A
	29	HREF="mandoc.1.html">mandoc</A>, which interfaces with the compiler library to format output for UNIX terminals (with
	30	support for wide-character locales), XHTML, HTML, PostScript, and PDF.
	31	It also includes <A HREF="preconv.1.html">preconv</A>, for recoding multibyte manuals; and <A
	32	HREF="makewhatis.1.html">makewhatis</A>, for indexing manuals.
	33	It is a <A CLASS="external" HREF="http://bsd.lv/">BSD.lv</A> project.
	34	</P>
	35	<P>
	36	<I>Disambiguation</I>: <SPAN CLASS="nm">mdocml</SPAN> is often referred to by its installed binary, <Q>mandoc</Q>.
	37	</P>
	38	<H1>
	39	<A NAME="sources">Sources</A>
	40	</H1>
	41	<P>
	42	<SPAN CLASS="nm">mdocml</SPAN> is in plain-old ANSI C and should build and run on any UNIX system, although <A
	43	HREF="makewhatis.1.html">makewhatis</A> requires <A CLASS="external"
	44	HREF="http://www.oracle.com/technetwork/database/berkeleydb/overview/index.html">Berkeley Database</A> (this is
	45	installed by default on all BSD operating systems).
	46	To compile <SPAN CLASS="nm">mdocml</SPAN>, run <CODE>make</CODE>, then <CODE>make install</CODE> to install into
	47	<I>/usr/local</I>.
	48	Be aware: if you have an existing <A HREF="http://www.gnu.org/software/groff/" CLASS="external">groff</A> installation,
	49	this may overwrite its <B>preconv</B> binary.
	50	The <A HREF="makewhatis.1.html">makewhatis</A> utility is not yet linked to the build. You must run <CODE>make
	51	makewhatis</CODE> to build it (it does not install).
	52	</P>
	53	<P>
	54	The most current version of <SPAN CLASS="nm">mdocml</SPAN> is <SPAN CLASS="attn">@VERSION@</SPAN>, dated <SPAN
	55	class="attn">@VDATE@</SPAN>.
	56	</P>
	57
	58	<H2>
	59	Current
	60	</H2>
	61
	62	<TABLE WIDTH="100%" SUMMARY="Current Sources">
	63	<COL WIDTH="175">
	64	<COL>
	65	<TBODY>
	66	<TR>
	67	<TD>Source archive</TD>
	68	<TD>
	69	<A HREF="/snapshots/mdocml.tar.gz">/snapshots/mdocml.tar.gz</A>
	70	<SMALL>(<A HREF="/snapshots/mdocml.md5">md5</A>)</SMALL>
	71	</TD>
	72	</TR>
	73	<TR>
	74	<TD>Online source</TD>
	75	<TD>
	76	<A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>
	77	</TD>
	78	</TR>
	79	</TBODY>
	80	</TABLE>
	81
	82	<H2>
	83	Downstream
	84	</H2>
	85
	86	<TABLE WIDTH="100%" SUMMARY="Downstream Sources">
	87	<COL WIDTH="175">
	88	<COL>
	89	<TBODY>
	90	<TR>
	91	<TD>DragonFly BSD</TD>
	92	<TD>
	93	<A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc"
	94	CLASS="external">usr.bin/mandoc</A>
	95	</TD>
	96	</TR>
	97	<TR>
	98	<TD>FreeBSD</TD>
	99	<TD>
	100	<A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/"
	101	CLASS="external">ports/textproc/mdocml</A>
	102	</TD>
	103	</TR>
	104	<TR>
	105	<TD>NetBSD</TD>
	106	<TD>
	107	<A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/"
	108	CLASS="external">src/external/bsd/mdocml</A>
	109	</TD>
	110	</TR>
	111	<TR>
	112	<TD>OpenBSD</TD>
	113	<TD>
	114	<A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/"
	115	CLASS="external">src/usr.bin/mandoc</A>
	116	</TD>
	117	</TR>
	118	</TBODY>
	119	</TABLE>
	120
	121	<H2>
	122	Historical
	123	</H2>
	124
	125	<TABLE WIDTH="100%" SUMMARY="Archived Sources">
	126	<COL WIDTH="175">
	127	<COL>
	128	<TBODY>
	129	<TR>
	130	<TD>Source archive</TD>
	131	<TD>
	132	<A HREF="/snapshots/">/snapshots/</A>
	133	</TD>
	134	</TR>
	135	</TBODY>
	136	</TABLE>
	137
	138	<H1>
	139	<A NAME="documentation">Documentation</A>
	140	</H1>
	141
	142	<P>
	143	These manuals are generated automatically and refer to the current snapshot.
	144	</P>
	145
	146	<TABLE WIDTH="100%" SUMMARY="Documentation">
	147	<COL WIDTH="175">
	148	<COL>
	149	<TBODY>
	150	<TR>
	151	<TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>
	152	<TD VALIGN="top">
	153	format and display UNIX manuals
	154	<SMALL>
	155	(<A HREF="mandoc.1.txt">text</A> \|
	156	<A HREF="mandoc.1.xhtml">xhtml</A> \|
	157	<A HREF="mandoc.1.pdf">pdf</A> \|
	158	<A HREF="mandoc.1.ps">postscript</A>)
	159	</SMALL>
	160	</TD>
	161	</TR>
	162	<TR>
	163	<TD VALIGN="top"><A HREF="makewhatis.1.html">makewhatis(1)</A></TD>
	164	<TD VALIGN="top">
	165	index UNIX manuals
	166	<SMALL>
	167	(<A HREF="makewhatis.1.txt">text</A> \|
	168	<A HREF="makewhatis.1.xhtml">xhtml</A> \|
	169	<A HREF="makewhatis.1.pdf">pdf</A> \|
	170	<A HREF="makewhatis.1.ps">postscript</A>)
	171	</SMALL>
	172	</TD>
	173	</TR>
	174	<TR>
	175	<TD VALIGN="top"><A HREF="preconv.1.html">preconv(1)</A></TD>
	176	<TD VALIGN="top">
	177	recode multibyte UNIX manuals
	178	<SMALL>
	179	(<A HREF="preconv.1.txt">text</A> \|
	180	<A HREF="preconv.1.xhtml">xhtml</A> \|
	181	<A HREF="preconv.1.pdf">pdf</A> \|
	182	<A HREF="preconv.1.ps">postscript</A>)
	183	</SMALL>
	184	</TD>
	185	</TR>
	186	<TR>
	187	<TD VALIGN="top"><A HREF="mandoc.3.html">mandoc(3)</A></TD>
	188	<TD VALIGN="top">
	189	mandoc macro compiler library
	190	<SMALL>
	191	(<A HREF="mandoc.3.txt">text</A> \|
	192	<A HREF="mandoc.3.xhtml">xhtml</A> \|
	193	<A HREF="mandoc.3.pdf">pdf</A> \|
	194	<A HREF="mandoc.3.ps">postscript</A>)
	195	</SMALL>
	196	</TD>
	197	</TR>
	198	<TR>
	199	<TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
	200	<TD VALIGN="top">
	201	man language reference
	202	<SMALL>
	203	(<A HREF="man.7.txt">text</A> \|
	204	<A HREF="man.7.xhtml">xhtml</A> \|
	205	<A HREF="man.7.pdf">pdf</A> \|
	206	<A HREF="man.7.ps">postscript</A>)
	207	</SMALL>
	208	</TD>
	209	</TR>
	210	<TR>
	211	<TD VALIGN="top"><A HREF="eqn.7.html">eqn(7)</A></TD>
	212	<TD VALIGN="top">
	213	eqn-mandoc language reference
	214	<SMALL>
	215	(<A HREF="eqn.7.txt">text</A> \|
	216	<A HREF="eqn.7.xhtml">xhtml</A> \|
	217	<A HREF="eqn.7.pdf">pdf</A> \|
	218	<A HREF="eqn.7.ps">postscript</A>)
	219	</SMALL>
	220	</TD>
	221	</TR>
	222	<TR>
	223	<TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
	224	<TD VALIGN="top">
	225	mandoc special characters
	226	<SMALL>
	227	(<A HREF="mandoc_char.7.txt">text</A> \|
	228	<A HREF="mandoc_char.7.xhtml">xhtml</A> \|
	229	<A HREF="mandoc_char.7.pdf">pdf</A> \|
	230	<A HREF="mandoc_char.7.ps">postscript</A>)
	231	</SMALL>
	232	</TD>
	233	</TR>
	234	<TR>
	235	<TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
	236	<TD VALIGN="top">
	237	mdoc language reference
	238	<SMALL>
	239	(<A HREF="mdoc.7.txt">text</A> \|
	240	<A HREF="mdoc.7.xhtml">xhtml</A> \|
	241	<A HREF="mdoc.7.pdf">pdf</A> \|
	242	<A HREF="mdoc.7.ps">postscript</A>)
	243	</SMALL>
	244	</TD>
	245	</TR>
	246	<TR>
	247	<TD VALIGN="top"><A HREF="roff.7.html">roff(7)</A></TD>
	248	<TD VALIGN="top">
	249	roff-mandoc language reference
	250	<SMALL>
	251	(<A HREF="roff.7.txt">text</A> \|
	252	<A HREF="roff.7.xhtml">xhtml</A> \|
	253	<A HREF="roff.7.pdf">pdf</A> \|
	254	<A HREF="roff.7.ps">postscript</A>)
	255	</SMALL>
	256	</TD>
	257	</TR>
	258	<TR>
	259	<TD VALIGN="top"><A HREF="tbl.7.html">tbl(7)</A></TD>
	260	<TD VALIGN="top">
	261	tbl-mandoc language reference
	262	<SMALL>
	263	(<A HREF="tbl.7.txt">text</A> \|
	264	<A HREF="tbl.7.xhtml">xhtml</A> \|
	265	<A HREF="tbl.7.pdf">pdf</A> \|
	266	<A HREF="tbl.7.ps">postscript</A>)
	267	</SMALL>
	268	</TD>
	269	</TR>
	270	</TBODY>
	271	</TABLE>
	272
	273	<H1>
	274	<A NAME="contact">Contact</A>
	275	</H1>
	276
	277	<P>
	278	Use the mailing lists for bug-reports, patches, questions, etc. (these require subscription). Please check the
	279	<A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml">TODO</A> for known issues
	280	before posting. Beyond that, contact Kristaps at <A
	281	HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&c=Q2DBUt401ePlSeupJFrq_Q==" TITLE="Reveal
	282	this e-mail address">kris...</A>@bsd.lv.
	283	</P>
	284
	285	<TABLE WIDTH="100%" SUMMARY="Mailing Lists">
	286	<COL WIDTH="175">
	287	<COL>
	288	<TBODY>
	289	<TR>
	290	<TD>
	291	disc<A CLASS="external" TITLE="Reveal this e-mail address"
	292	HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
	293	</TD>
	294	<TD>
	295	bug-reports, general questions, and announcements
	296	<SMALL>(<A HREF="/archives/discuss/summary.html">archive</A>)</SMALL>
	297	</TD>
	298	</TR>
	299	<TR>
	300	<TD>
	301	tec<A CLASS="external" TITLE="Reveal this e-mail address"
	302	HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
	303	</TD>
	304	<TD>
	305	patches and system discussions
	306	<SMALL>(<A HREF="/archives/tech/summary.html">archive</A>)</SMALL>
	307	</TD>
	308	</TR>
	309	<TR>
	310	<TD>
	311	sou<A CLASS="external" TITLE="Reveal this e-mail address"
	312	HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
	313	</TD>
	314	<TD>
	315	source commit messages
	316	<SMALL>(<A HREF="/archives/source/summary.html">archive</A>)</SMALL>
	317	</TD>
	318	</TR>
	319	</TBODY>
	320	</TABLE>
	321
	322	<H1>
	323	<A NAME="news">News</A>
	324	</H1>
	325
	326	<P CLASS="news">
	327	26-05-2011: version 1.11.3
	328	</P>
	329	<P>
	330	Introduce locale-encoding of output with the <B>-Tlocale</B> output option and Unicode escaped-character input.
	331	See <A HREF="mandoc.1.html">mandoc</A> and <A HREF="mandoc_char.7.html">mandoc_char</A>, respectively, for details.
	332	This allows for non-ASCII characters (e.g., <I>\[u5000]</I>) to be rendered in the locale's encoding, if said
	333	environment supports wide-character encoding (if it does not, <B>-Tascii</B> is used instead).
	334	Locale support can be turned off at compile time by removing <I>-DUSE_WCHAR</I> in the <I>Makefile</I>, in which case
	335	<B>-Tlocale</B> is always a synonym for <B>-Tascii</B>.
	336	</P>
	337	<P>
	338	Furthermore, multibyte-encoded documents, such as those in UTF-8, may be on-the-fly recoded into <A
	339	HREF="mandoc.1.html">mandoc</A> input by using the newly-added <A HREF="preconv.1.html">preconv</A> utility.
	340	Note: in the future, this feature may be integrated into <A HREF="mandoc.1.html">mandoc</A>.
	341	</P>
	342
	343	<P CLASS="news">
	344	12-05-2011: version 1.11.2
	345	</P>
	346	<P>
	347	Corrected some installation issues in version 1.11.1.
	348	Further migration to <A HREF="mandoc.3.html">libmandoc</A>.
	349	Initial public release (this utility is very much under development) of <A HREF="makewhatis.1.html">makewhatis</A>,
	350	initially named mandoc-db.
	351	This utility produces keyword databases of manual content
	352	<A HREF="http://mdocml.bsd.lv/mandoc-cgi/index.html">mandoc-cgi</A>, which features semantic querying of manual content.
	353	</P>
	354
	355	<P CLASS="news">
	356	04-04-2011: version 1.11.1
	357	</P>
	358	<P>
	359	The earlier <I>libroff</I>, <I>libmdoc</I>, and <I>libman</I> soup have been merged into
	360	a single library, <A HREF="mandoc.3.html">libmandoc</A>, which manages all aspects of
	361	parsing real manuals (from line-handling to <A HREF="tbl.7.html">tbl</A> parsing).
	362	</P>
	363	<P>
	364	Beyond this structural change, initial <A HREF="eqn.7.html">eqn</A> functionality is in
	365	place. For the time being, this is limited to the recognition of equation blocks;
	366	future version of <SPAN CLASS="nm">mdocml</SPAN> will expand upon this framework.
	367	</P>
	368	<P>
	369	As usual, many general fixes and improvements have also occurred. In particular, a great
	370	deal of redundancy and superfluous code has been removed with the merging of the backend
	371	libraries.
	372	</P>
	373
	374	<P>
	375	See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
	376	historical notes.
	377	</P>
	378
	379	<P CLASS="foot">
	380	<SMALL>
	381	Copyright © 2008–2011
	382	<A CLASS="external" HREF="http://kristaps.bsd.lv">Kristaps Dzonsons</A>,
	383	$Date: 2011/05/26 21:23:50 $
	384	</SMALL>
	385	</P>
	386	</BODY>
	387	</HTML>