summaryrefslogtreecommitdiffstats
path: root/mandoc.1
Commit message (Collapse)AuthorAgeFilesLines
* Implement the man(7) .MR macro, a 2023 GNU extension.Ingo Schwarze2023-10-241-7/+17
| | | | | | | | | | | The syntax and semantics is almost identical to mdoc(7) .Xr. This will be needed for reading the groff manual pages once our port will be updated to 1.23, and the Linux Manual Pages Project is also determined to start using it sooner or later. I did not advocate for this new macro, but since we want to remain able to read all manual pages found in the wild, there is little choice but to support it. At least it is easy to do, they basically copied .Xr.
* Better document the purpose and features of the file mandoc.cssIngo Schwarze2023-10-181-13/+42
| | | | | | and the purpose and limitations of the embedded stylesheet. Triggered by a conversation with Alejandro Colomar <alx at kernel dot org>.
* Denote multiple arguments with 'arg ...' not 'args'.Ingo Schwarze2023-04-281-4/+2
| | | | From kn@, OK jmc@.
* If the body of a man(7) .MT or .UR block is empty, do not emit a warning.Ingo Schwarze2022-08-021-3/+1
| | | | | | | | | | | | | | | Leaving the body empty is legitimate in this case if the author only wants to display a mail address or URI without providing a link text. Output modules already handle this correctly: terminal output shows just the URI without an accompanying text, HTML output uses the URI for *both* the href= attribute and as the content of the <a> element. The documentation was also wrong and claimed that an .MT or .UR block with an empty body would produce no output. As explained above, this isn't true. Bogus warning reported by Alejandro Colomar <alx dot manpages at gmail dot com>.
* spelling; patch from jsg@Ingo Schwarze2022-07-031-1/+1
|
* Delete the statement that the default stylesheet only used CSS1Ingo Schwarze2022-06-221-1/+0
| | | | | | | | | | | | | | | | because that has no longer been true for some time now. I would certainly like to adhere to a coherent standard and state which one that is. Unfortunately, the W3C deliberately smashed the CSS standard into pieces such that a coherent standard no longer exists and such that statements about standard conformance have become next to meaningless. Consequently, i now remain reluctantly silent regarding CSS standard(s) conformance. Going back to CSS2.1, published in 2011, which was the last CSS standard in the proper sense of the word, is not an option because it has gaping holes in functionality and is no longer adequate for use on today's WWW.
* Split the excessively generic diagnostic message "invalid escape sequence"Ingo Schwarze2022-06-071-3/+14
| | | | | into the more specific messages "invalid escape argument delimiter" and "invalid escape sequence argument".
* With the improved escape sequence parser, it becomes easy to also improveIngo Schwarze2022-06-051-15/+45
| | | | | | | | | diagnostics. Distinguish "incomplete escape sequence", "invalid special character", and "unknown special character" from the generic "invalid escape sequence", also promoting them from WARNING to ERROR because incomplete escape sequences are severe syntax violations and because encountering an invalid or unknown special character makes it likely that part of the document content intended by the authors gets lost.
* The syntax of the roff(7) .mc request is quite specialIngo Schwarze2022-04-281-0/+16
| | | | | | | | | and the roff_onearg() parsing function is too generic, so provide a dedicated parsing function instead. This fixes an assertion failure when an \o escape sequence is passed as the argument; the bug was found by tb@ using afl(1). It also makes mandoc output more similar to groff in various cases.
* If a .shift request has a negative argument, do not use a negative arrayIngo Schwarze2022-04-241-1/+8
| | | | | | | | index but use 0 instead of the argument, just like groff. Warn about the invalid argument. While here, fix the column number in another warning message. Segfault reported by tb@, found with afl(1).
* prefer https links in man pagesIngo Schwarze2022-04-141-3/+3
| | | | | patch from jsg@ ok gnezdo@ miod@ jmc@
* In the first example, use "mandoc -a" directly rather "mandoc -l".Ingo Schwarze2022-02-081-1/+1
| | | | | | | | | | | | | It feels more natural to me to use -a directly when asking mandoc(1) to use a pager. The reason that "mandoc -l" does exactly the same as "mandoc -a" is that "mandoc" is essentially "man -lc", so the -a implied by -l negates the -c and the -l has no effect because it is already the default for mandoc(1). The more usual command for doing the same is "man -l foo.1 bar.1 ..." but that's off-topic for the mandoc(1) manual page. Patch on tech@ from Anders Damsgaard <anders at adamsgaard dot dk>.
* remove "please" from manual page;Ingo Schwarze2022-02-081-1/+1
| | | | patch from jsg@, ok jmc@ sthen@ millert@
* print a BAGARG message if -T markdown is requested on man(7) input;Ingo Schwarze2021-08-141-0/+8
| | | | suggested by Michael Stapelberg at debian dot org
* The mandoc(1) manual already mentions that -T man output modeIngo Schwarze2021-07-041-0/+20
| | | | | | | | | | neither supports tbl(7) nor eqn(7) input. If an input file contains such code anyway, tell the user rather than failing an assert(3)ion. Fixing a crash reported by Bjarni Ingi Gislason <bjarniig at rhi dot hi dot is> in https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=901636 which the Debian maintainer of mandoc, Michael at Stapelberg dot ch, forwarded to me.
* In terminal output of man(7) documents, stop printing two extra blankIngo Schwarze2021-06-281-2/+2
| | | | | | | | | | | lines before the NAME section and before the page footer. While these blank lines had a long tradition, they didn't really serve any purpose and merely wasted screen real estate. Besides, this makes output from man(7) more similar to output from mdoc(7). This commit keeps mandoc compatible with groff-current, where G. Branden Robinson committed the same change on June 16 (groff commit 2278d6ed).
* add a style message about overlong text lines,Ingo Schwarze2021-06-271-0/+3
| | | | | | | | trying very hard to avoid false positives, not at all trying to catch as many cases as possible; feature originally suggested by tb@, OK tb@ kn@ jmc@
* In -W style mode, check .Xr links along the full manpath becauseIngo Schwarze2021-06-021-9/+30
| | | | | | | | | | | that is more useful for validating manuals of non-base software. Nothing changes in -W all mode: by default for -T lint, we still assume we want to check base system conventions, including usually not wanting to link to non-base manual pages. The use case, a partial idea how to handle it, and a preliminary patch was originally presented by kn@, then refined by me. Final patch tested and OK'ed by kn@.
* Ignore unreasonably large spacing modifiers in tbl layouts.Ingo Schwarze2020-09-011-0/+4
| | | | | | Jan Schreiber <jes at posteo dot de> ran afl on mandoc and it turned out mandoc tried to use spacing modifiers so large that they would trigger assertion failures in term_ascii.c, function locale_advance().
* Remove a lie reported by Jamie Landeg-Jones <jamie at catflap dot org>:Ingo Schwarze2020-08-271-4/+1
| | | | | The times when -T man may have expanded .so requests are long gone, nor would such a feature be useful. Use soelim(1) if you need that.
* Make it more explicit that the statement "-O tag does not work with less(1)"Ingo Schwarze2020-08-271-1/+8
| | | | | | only applies to -T html output mode, and why. Of course, -O tag works just fine with less(1) in the -T ascii and -T utf8 output modes. Potential for confusion pointed out by Ian Ropers.
* Switch the default pager from "more -s" to "less".Ingo Schwarze2020-07-201-5/+4
| | | | | | | | | | | | | | | | | | | | | | POSIX explicitly allows using a different default pager if that is documented. Nowadays, the pager provided in most operating systems is less(1). Our man(1) implementation uses less(1) features that traditional more(1) did not provide, in particular tagging. Besides, as noted by deraadt@, the user interface of less(1) is slightly more refined and preferable over the user inferface of more(1). This switch was originally suggested by Ian Ropers. In ./configure, test whether less(1) is available. If not, fall back to more(1). In ./configure.local, support overriding the automatic test by setting BINM_PAGER. As explained by jmc@ and deraadt@, the -s flag was added a very long time ago when an antique version of groff(1) had an annoying bug in terminal output that would randomly display blank lines in the middle of pages. Clearly, -s has no longer been needed for many years, so drop it from the default pager invocation. OK deraadt@ jmc@ martijn@ job@ on the OpenBSD version of this patch.
* document -T html -O tag as implemented in main.c rev. 1.350Ingo Schwarze2020-06-151-0/+17
|
* provide a STYLE message when mandoc knows the file name and the extensionIngo Schwarze2020-04-241-2/+16
| | | | | disagrees with the section number given in the .Dt or .TH macro; feature suggested and patch tested by jmc@
* mention that -T man does not support eqn(7) and tbl(7);Ingo Schwarze2020-02-151-1/+6
| | | | triggered by a question from Stephen Gregoratto <dev at sgregoratto dot me>
* Align to the new, sane behaviour of the groff_mdoc(7) .Dd macro:Ingo Schwarze2020-01-191-1/+1
| | | | | | | | without an argument, use the empty string, and always concatenate all arguments, no matter their number. This allows reducing the number of arguments of mandoc_normdate() and some other simplifications, at the same time polishing some error messages by adding the name of the macro in question.
* Some time ago, i simplified mandoc_msg() such that it can be usedIngo Schwarze2019-07-101-4/+47
| | | | | | | | | everywhere and not only in the parsers. For more uniform messages, use it at more places instead of err(3), in particular in the main program. While here, integrate a few trivial functions called at exactly one place into the main option parser, and let a few more functions use the normal convention of returning 0 for success and -1 for error.
* use proper crossreference; patch from naddy@Ingo Schwarze2019-05-261-1/+2
|
* improve the description of the message "blank line in fill mode";Ingo Schwarze2019-04-301-1/+4
| | | | triggered by a misunderstanding by sashan@
* Explain the ASCII rendering of single quotes because that repeatedlyIngo Schwarze2019-02-231-0/+11
| | | | | | | | | | | caused confusion in the past. People plainly do not expect that there are limits to the compatibility between Unicode and ASCII, but there are. The information belongs here and not into mandoc_char(7) because it explains how the specific output device (-T ascii) works and because it has nothing to do with the question of how characters are represented on the input side.
* Support taking the -O tag value from apropos(1) key=value search terms;Ingo Schwarze2019-01-011-2/+10
| | | | | | feature improvement suggested by kn@. While here, also make "-O value" work from standard input. OK kn@
* add some notes about using col(1) and ul(1) to process the ascii markupIngo Schwarze2018-12-281-0/+7
| | | | | | since these may not be commonly known utilities; idea from and joint work with tedu@ CV: ----------------------------------------------------------------------
* mandoc.css lives in /usr/share/misc now; use full paths to indicate this.Ingo Schwarze2018-12-241-7/+7
| | | | from tedu@
* Explain what the fields in mandoc messages mean,Ingo Schwarze2018-12-201-3/+19
| | | | | | rather than merely specifying the message syntax. Gap in documentation found while looking at a bug report from Raf Czlonka <rczlonka at gmail dot com>.
* Several improvements to escape sequence handling.Ingo Schwarze2018-12-151-1/+15
| | | | | | | | | | | | | | | | | | | | | | | * Add the missing special character \_ (underscore). * Partial implementations of \a (leader character) and \E (uninterpreted escape character). * Parse and ignore \r (reverse line feed). * Add a WARNING message about undefined escape sequences. * Add an UNSUPP message about unsupported escape sequences. * Mark \! and \? (transparent throughput) and \O (suppress output) as unsupported. * Treat the various variants of zero-width spaces as one-byte escape sequences rather than as special characters, to avoid defining bogus forms with square brackets. * For special characters with one-byte names, do not define bogus forms with square brackets, except for \[-], which is valid. * In the form with square brackets, undefined special characters do not fall back to printing the name verbatim, not even for one-byte names. * Starting a special character name with a blank is an error. * Undefined escape sequences never abort formatting of the input string, not even in HTML output mode. * Document the newly handled escapes, and a few that were missing. * Regression tests for most of the above.
* In -T locale (the default), -T ascii, and -T utf8 mode, provide a newIngo Schwarze2018-11-221-0/+12
| | | | | | | | | | | | | | | output option -O tag[=term] to move right to the definition of "term" when opening the manual page in a pager, effectively porting the -T html fragment name feature - https://man.openbsd.org/ksh#ulimit - to the terminal. Try: $ man -O tag uvm_sysctl $ man -O tag=ulimit ksh $ man -O tag 3 compress Feature development triggered by a question from kn@. Klemens also tested, provided feedback that resulted in improvements, and provided an OK.
* Add an option -T html -O toc to add a brief table of contents nearIngo Schwarze2018-10-021-0/+3
| | | | | the top of HTML pages containing at least two non-standard sections. Suggested by Adam Kalisz and discussed with kristaps@ during EuroBSDCon 2018.
* Support a second argument to -O man,Ingo Schwarze2018-10-021-1/+5
| | | | | | selecting the format according to local existence of the file. Suggested by kristaps@ during EuroBSDCon 2018. Written on the train Frankfurt-Karlsruhe returning from EuroBSDCon.
* Rudimentary implementation of the roff(7) .char (output glyphIngo Schwarze2018-08-251-0/+13
| | | | | | | | | definition) request, used for example by groff_hdtbl(7). This simplistic implementation may interact incorrectly with the .tr (input character translation) request. But come on, you are not only using .char *and* .tr, but you do so with respect to the same character in the same manual page?
* Implement the roff(7) .shift and .return requests,Ingo Schwarze2018-08-231-0/+22
| | | | | | | | | | | | | | for example used by groff_hdtbl(7) and groff_mom(7). Also correctly interpolate arguments during nested macro execution even after .shift and .return, implemented using a stack of argument arrays. Note that only read.c, but not roff.c can detect the end of a macro execution, and the existence of .shift implies that arguments cannot be interpolated up front, so unfortunately, this includes a partial revert of roff.c rev. 1.337, moving argument interpolation back into the function roff_res().
* Issue a STYLE message when normalizing the date format in .Dd/.TH.Ingo Schwarze2018-07-281-0/+10
| | | | | | | | Leah Neukirchen pointed out that mdoclint(1) used to warn about a leading zero before the day number, so we know that both NetBSD and Void Linux want the message. It does no harm on OpenBSD because Mdocdate always does the right thing anyway. jmc@ agrees that it makes sense in contexts not using Mdocdate.
* Minor correction: we render HTML character references hexadecimal,Ingo Schwarze2018-05-031-1/+1
| | | | not decimal; bentley@ changed that in html.c on July 14, 2017.
* Simpler description of output formats, shortening the manual page by 15 lines.Ingo Schwarze2018-04-291-99/+85
| | | | | | | Avoid the double redirection from -Tutf8 via -Tlocale to -Tascii. Add LC_CTYPE to the ENVIRONMENT section. While here, also correct a few inaccuracies and tweak some wordings. Triggered by a question from Laura Morales <lauretas at mail dot com>.
* Use TIOCGWINSZ to reduce the default -Owidth during interactive useIngo Schwarze2018-04-131-4/+8
| | | | | | | on terminals narrower than 79 columns and the default -Oindent on terminals narrower than 66 columns. Requested by and feedback from pirofti@; mpi@ and juanfra@ also like the general direction.
* Style message about bad input encoding of em-dashes as -- instead of \(em.Ingo Schwarze2018-03-161-1/+7
| | | | Suggested by Thomas Klausner <wiz at NetBSD>; discussed with jmc@.
* duplicate word, found by igor(1)Ingo Schwarze2017-11-281-1/+1
|
* be less assertive when warning about a possible typo;Ingo Schwarze2017-11-101-1/+1
| | | | from jca@, ok jmc@
* typo: convertion -> convention; from dcoppa@Ingo Schwarze2017-09-071-1/+1
|
* document -O mdoc; triggered by a question from jmc@ and OK jmc@Ingo Schwarze2017-08-191-0/+14
|
* For -Tlint, put parser messages on stdout instead of stderr.Ingo Schwarze2017-07-201-1/+3
| | | | | | | | | | | Originally, naddy@ requested this in 2011 (or maybe even earlier). It was discussed with joerg@, kristaps@, naddy@, and espie@ in 2011, and everybody agreed in principle, but it was postponed because kristaps@ wanted to do some cleanup of the message system first. Meanwhile, message infrastructure was improved about a dozen times... This makes long, tedious commands like "mandoc -Tlint *.1 2>&1 | less" unnecessary and allows simple ones like "man -l -Tlint *.1".
generated by cgit (git 2.34.1) at 2024-11-18 04:13:26 +0000