| blob | 0f5b557f4e78fe9272b4785858033053ea888536 |
1 /* $Id: mdoc_macro.c,v 1.139 2014/08/01 17:27:44 schwarze Exp $ */
2 /*
3 * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv>
4 * Copyright (c) 2010, 2012, 2013 Ingo Schwarze <schwarze@openbsd.org>
5 *
6 * Permission to use, copy, modify, and distribute this software for any
7 * purpose with or without fee is hereby granted, provided that the above
8 * copyright notice and this permission notice appear in all copies.
9 *
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 */
18 #ifdef HAVE_CONFIG_H
20 #endif
22 #include <assert.h>
23 #include <ctype.h>
24 #include <stdlib.h>
25 #include <stdio.h>
26 #include <string.h>
27 #include <time.h>
35 REWIND_NONE,
36 REWIND_THIS,
37 REWIND_MORE,
38 REWIND_FORCE,
39 REWIND_LATER,
40 REWIND_ERROR
41 };
214 };
219 /*
220 * This is called at the end of parsing. It must traverse up the tree,
221 * closing out open [implicit] scopes. Obviously, open explicit scopes
222 * are errors.
223 */
224 int
226 {
229 /* Scan for open explicit scopes. */
240 /* Rewind to the first. */
243 }
245 /*
246 * Look up a macro from within a subsequent context.
247 */
248 static enum mdoct
250 {
255 }
257 /*
258 * Lookup a macro following the initial line macro.
259 */
260 static enum mdoct
262 {
270 }
272 static int
274 {
282 /*
283 * Save the parent here, because we may delete the
284 * mdoc->last node in the post-validation phase and reset
285 * it to mdoc->last->parent, causing a step in the closing
286 * out to be lost.
287 */
295 }
298 }
300 /*
301 * For a block closing macro, return the corresponding opening one.
302 * Otherwise, return the macro itself.
303 */
304 static enum mdoct
306 {
342 }
343 /* NOTREACHED */
344 }
346 /*
347 * Rewinding to tok, how do we have to handle *p?
348 * REWIND_NONE: *p would delimit tok, but no tok scope is open
349 * inside *p, so there is no need to rewind anything at all.
350 * REWIND_THIS: *p matches tok, so rewind *p and nothing else.
351 * REWIND_MORE: *p is implicit, rewind it and keep searching for tok.
352 * REWIND_FORCE: *p is explicit, but tok is full, force rewinding *p.
353 * REWIND_LATER: *p is explicit and still open, postpone rewinding.
354 * REWIND_ERROR: No tok block is open at all.
355 */
356 static enum rew
359 {
361 /*
362 * No matching token, no delimiting block, no broken block.
363 * This can happen when full implicit macros are called for
364 * the first time but try to rewind their previous
365 * instance anyway.
366 */
372 /*
373 * When starting to rewind, skip plain text
374 * and nodes that have already been rewound.
375 */
379 /*
380 * The easiest case: Found a matching token.
381 * This applies to both blocks and elements.
382 */
388 /*
389 * While elements do require rewinding for themselves,
390 * they never affect rewinding of other nodes.
391 */
395 /*
396 * Blocks delimited by our target token get REWIND_MORE.
397 * Blocks delimiting our target token get REWIND_NONE.
398 */
408 /*
409 * XXX Badly nested block handling still fails badly
410 * when one block is breaking two blocks of the same type.
411 * This is an incomplete and extremely ugly workaround,
412 * required to let the OpenBSD tree build.
413 */
421 /* FALLTHROUGH */
425 /* FALLTHROUGH */
435 }
437 /*
438 * Default block rewinding rules.
439 * In particular, always skip block end markers,
440 * and let all blocks rewind Nm children.
441 */
447 /*
448 * By default, closing out full blocks
449 * forces closing of broken explicit blocks,
450 * while closing out partial blocks
451 * allows delayed rewinding by default.
452 */
455 }
457 static int
459 {
469 }
471 /*
472 * We are trying to close a block identified by tok,
473 * but the child block *broken is still open.
474 * Thus, postpone closing the tok block
475 * until the rew_sub call closing *broken.
476 */
477 static int
480 {
483 /*
484 * Iterate backwards, searching for the block matching tok,
485 * that is, the block breaking the *broken block.
486 */
489 /*
490 * If the *broken block had already been broken before
491 * and we encounter its breaker, make the tok block
492 * pending on the inner breaker.
493 * Graphically, "[A breaker=[B broken=[C->B B] tok=A] C]"
494 * becomes "[A broken=[B [C->B B] tok=A] C]"
495 * and finally "[A [B->A [C->B B] A] C]".
496 */
500 }
507 /*
508 * Found the breaker.
509 * If another, outer breaker is already pending on
510 * the *broken block, we must not clobber the link
511 * to the outer breaker, but make it pending on the
512 * new, now inner breaker.
513 * Graphically, "[A breaker=[B broken=[C->A A] tok=B] C]"
514 * becomes "[A breaker=[B->A broken=[C A] tok=B] C]"
515 * and finally "[A [B->A [C->B A] B] C]".
516 */
520 /*
521 * If the breaker had also been broken before,
522 * it cannot take on the outer breaker itself,
523 * but must hand it on to its own breakers.
524 * Graphically, this is the following situation:
525 * "[A [B breaker=[C->B B] broken=[D->A A] tok=C] D]"
526 * "[A taker=[B->A breaker=[C->B B] [D->C A] C] D]"
527 */
532 }
538 }
540 /*
541 * Found no matching block for tok.
542 * Are you trying to close a block that is not open?
543 */
545 }
547 static int
550 {
568 /* FALLTHROUGH */
578 /* FALLTHROUGH */
584 }
586 }
592 /*
593 * The current block extends an enclosing block.
594 * Now that the current block ends, close the enclosing block, too.
595 */
602 }
605 }
607 /*
608 * Allocate a word and check whether it's punctuation or not.
609 * Punctuation consists of those tokens found in mdoc_isdelim().
610 */
611 static int
614 {
625 }
633 /*
634 * Closing delimiters only suppress the preceding space
635 * when they follow something, not when they start a new
636 * block or element, and not when they follow `No'.
637 *
638 * XXX Explicitly special-casing MDOC_No here feels
639 * like a layering violation. Find a better way
640 * and solve this in the code related to `No'!
641 */
649 }
651 static int
653 {
672 /*
673 * If we encounter end-of-sentence symbols, then trigger
674 * the double-space.
675 *
676 * XXX: it's easy to allow this to propagate outward to
677 * the last symbol, such that `. )' will cause the
678 * correct double-spacing. However, (1) groff isn't
679 * smart enough to do this and (2) it would require
680 * knowing which symbols break this behaviour, for
681 * example, `. ;' shouldn't propagate the double-space.
682 */
685 }
688 }
690 /*
691 * Close out block partial/full explicit.
692 */
693 static int
695 {
716 }
718 /*
719 * Search backwards for beginnings of blocks,
720 * both of our own and of pending sub-blocks.
721 */
728 /* Remember the start of our own body. */
733 }
740 /*
741 * Found the start of our own block.
742 * When there is no pending sub block,
743 * just proceed to closing out.
744 */
748 /*
749 * When there is a pending sub block,
750 * postpone closing out the current block
751 * until the rew_sub() closing out the sub-block.
752 */
755 /*
756 * Mark the place where the formatting - but not
757 * the scope - of the current block ends.
758 */
763 }
765 /*
766 * When finding an open sub block, remember the last
767 * open explicit block, or, in case there are only
768 * implicit ones, the first open implicit block.
769 */
775 }
786 }
802 }
820 }
826 }
833 }
841 }
843 static int
845 {
856 /*
857 * Whether we allow ignored elements (those without content,
858 * usually because of reserved words) to squeak by.
859 */
863 /* FALLTHROUGH */
865 /* FALLTHROUGH */
867 /* FALLTHROUGH */
869 /* FALLTHROUGH */
871 /* FALLTHROUGH */
878 }
887 }
895 }
910 /*
911 * In this case, we've located a submacro and must
912 * execute it. Close out scope, if open. If no
913 * elements have been generated, either create one (nc)
914 * or raise a warning.
915 */
931 }
938 }
940 /*
941 * Non-quote-enclosed punctuation. Set up our scope, if
942 * a word; rewind the scope, if a delimiter; then append
943 * the word.
944 */
949 /*
950 * If we encounter closing punctuation, no word
951 * has been omitted, no scope is open, and we're
952 * allowed to have an empty element, then start
953 * a new scope. `Ar', `Fl', and `Li', only do
954 * this once per invocation. There may be more
955 * of these (all of them?).
956 */
964 cnt++;
966 }
967 /*
968 * Close out our scope, if one is open, before
969 * any punctuation.
970 */
978 }
981 cnt++;
987 /*
988 * `Fl' macros have their scope re-opened with each new
989 * word so that the `-' can be added to each one without
990 * having to parse out spaces.
991 */
996 }
997 }
1002 /*
1003 * If no elements have been collected and we're allowed to have
1004 * empties (nc), open a scope and close it out. Otherwise,
1005 * raise a warning.
1006 */
1017 }
1022 }
1024 static int
1026 {
1040 /* Skip items outside lists. */
1053 }
1054 }
1056 /* Close out prior implicit scope. */
1063 }
1065 /*
1066 * This routine accommodates implicitly- and explicitly-scoped
1067 * macro openings. Implicit ones first close out prior scope
1068 * (seen above). Delay opening the head until necessary to
1069 * allow leading punctuation to print. Special consideration
1070 * for `It -column', which has phrase-part syntax instead of
1071 * regular child nodes.
1072 */
1081 }
1090 }
1097 /*
1098 * Exception: Heads of `It' macros in `-diag' lists are not
1099 * parsed, even though `It' macros in general are parsed.
1100 */
1105 /*
1106 * The `Nd' macro has all arguments in its body: it's a hybrid
1107 * of block partial-explicit and full-implicit. Stupid.
1108 */
1119 }
1128 /* Initialise last-phrase-type with ARGS_PEND. */
1141 /*
1142 * This is necessary: if the last token on a
1143 * line is a `Ta' or tab, then we'll get
1144 * ARGS_EOLN, so we must be smart enough to
1145 * reopen our scope if the last parse was a
1146 * phrase or partial phrase.
1147 */
1154 }
1156 /*
1157 * Emit leading punctuation (i.e., punctuation before
1158 * the MDOC_HEAD) for non-phrase types.
1159 */
1170 }
1172 /* Open a head if one hasn't been opened. */
1178 }
1183 /*
1184 * If we haven't opened a body yet, rewind the
1185 * head; if we have, rewind that instead.
1186 */
1192 /* Then allocate our body context. */
1198 /*
1199 * Process phrases: set whether we're in a
1200 * partial-phrase (this effects line handling)
1201 * then call down into the phrase parser.
1202 */
1214 }
1224 }
1229 }
1235 }
1240 /* If we've already opened our body, exit now. */
1245 /*
1246 * If there is an open (i.e., unvalidated) sub-block requiring
1247 * explicit close-out, postpone switching the current block from
1248 * head to body until the rew_sub() call closing out that
1249 * sub-block.
1250 */
1257 }
1258 }
1260 /* Close out scopes to remain in a consistent state. */
1267 out:
1278 }
1280 static int
1282 {
1293 /*
1294 * A macro that spans to the end of the line. This is generally
1295 * (but not necessarily) called as the first macro. The block
1296 * has a head as the immediate child, which is always empty,
1297 * followed by zero or more opening punctuation nodes, then the
1298 * body (which may be empty, depending on the macro), then zero
1299 * or more closing punctuation nodes.
1300 */
1312 /*
1313 * Open the body scope "on-demand", that is, after we've
1314 * processed all our the leading delimiters (open parenthesis,
1315 * etc.).
1316 */
1334 }
1340 }
1349 }
1354 }
1356 /* Clean-ups to leave in a consistent state. */
1362 }
1364 /*
1365 * If there is an open sub-block requiring explicit close-out,
1366 * postpone closing out the current block
1367 * until the rew_sub() call closing out the sub-block.
1368 */
1379 }
1380 }
1386 /* Standard appending of delimiters. */
1391 /* Rewind scope, if applicable. */
1396 /* Move trailing .Ns out of scope. */
1404 }
1406 static int
1408 {
1418 /*
1419 * The opening of an explicit macro having zero or more leading
1420 * punctuation nodes; a head with optional single element (the
1421 * case of `Eo'); and a body that may be empty.
1422 */
1438 /* Flush out leading punctuation. */
1446 }
1453 }
1455 /*
1456 * `Eo' gobbles any data into the head, but most other
1457 * macros just immediately close out and begin the body.
1458 */
1462 /* No check whether it's a macro! */
1475 }
1486 }
1491 }
1493 /* Clean-up to leave in a consistent state. */
1504 }
1506 /* Standard appending of delimiters. */
1511 }
1513 static int
1515 {
1525 /*
1526 * A line macro that has a fixed number of arguments (maxargs).
1527 * Only open the scope once the first non-leading-punctuation is
1528 * found (unless MDOC_IGNDELIM is noted, like in `Pf'), then
1529 * keep it open until the maximum number of arguments are
1530 * exhausted.
1531 */
1535 /* FALLTHROUGH */
1537 /* FALLTHROUGH */
1539 /* FALLTHROUGH */
1544 /* FALLTHROUGH */
1546 /* FALLTHROUGH */
1553 }
1562 }
1571 }
1598 }
1608 j++;
1610 }
1619 }
1624 j++;
1625 }
1630 /* Close out in a consistent state. */
1637 }
1639 static int
1641 {
1654 /* Parse macro arguments. */
1663 }
1671 }
1673 /* Open element scope. */
1678 /* Parse argument terms. */
1696 }
1701 }
1703 /* Close out (no delimiters). */
1706 }
1708 static int
1710 {
1715 /* If we're not in the SYNOPSIS, go straight to in-line. */
1719 /* If we're a nested call, same place. */
1723 /*
1724 * XXX: this will open a block scope; however, if later we end
1725 * up formatting the block scope, then child nodes will inherit
1726 * the formatting. Be careful.
1727 */
1732 }
1734 /*
1735 * Phrases occur within `Bl -column' entries, separated by `Ta' or tabs.
1736 * They're unusual because they're basically free-form text until a
1737 * macro is encountered.
1738 */
1739 static int
1741 {
1763 }
1768 }
1771 }
1773 static int
1775 {
1782 /* Make sure we are in a column list or ignore this macro. */
1790 }
1792 /* Advance to the next column. */
1814 }
1819 }
1822 }