| blob | 2a63ca92e31d2ae37d7b5be76f50d94815f4eb26 |
1 /* $Id: mdoc_macro.c,v 1.125 2013/12/24 20:45:27 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. */
239 /* Rewind to the first. */
242 }
245 /*
246 * Look up a macro from within a subsequent context.
247 */
248 static enum mdoct
250 {
255 }
258 /*
259 * Lookup a macro following the initial line macro.
260 */
261 static enum mdoct
263 {
271 }
274 static int
276 {
282 /* LINTED */
284 /*
285 * Save the parent here, because we may delete the
286 * mdoc->last node in the post-validation phase and reset
287 * it to mdoc->last->parent, causing a step in the closing
288 * out to be lost.
289 */
297 }
300 }
303 /*
304 * For a block closing macro, return the corresponding opening one.
305 * Otherwise, return the macro itself.
306 */
307 static enum mdoct
309 {
345 }
346 /* NOTREACHED */
347 }
350 /*
351 * Rewinding to tok, how do we have to handle *p?
352 * REWIND_NONE: *p would delimit tok, but no tok scope is open
353 * inside *p, so there is no need to rewind anything at all.
354 * REWIND_THIS: *p matches tok, so rewind *p and nothing else.
355 * REWIND_MORE: *p is implicit, rewind it and keep searching for tok.
356 * REWIND_FORCE: *p is explicit, but tok is full, force rewinding *p.
357 * REWIND_LATER: *p is explicit and still open, postpone rewinding.
358 * REWIND_ERROR: No tok block is open at all.
359 */
360 static enum rew
363 {
365 /*
366 * No matching token, no delimiting block, no broken block.
367 * This can happen when full implicit macros are called for
368 * the first time but try to rewind their previous
369 * instance anyway.
370 */
376 /*
377 * When starting to rewind, skip plain text
378 * and nodes that have already been rewound.
379 */
383 /*
384 * The easiest case: Found a matching token.
385 * This applies to both blocks and elements.
386 */
392 /*
393 * While elements do require rewinding for themselves,
394 * they never affect rewinding of other nodes.
395 */
399 /*
400 * Blocks delimited by our target token get REWIND_MORE.
401 * Blocks delimiting our target token get REWIND_NONE.
402 */
412 /*
413 * XXX Badly nested block handling still fails badly
414 * when one block is breaking two blocks of the same type.
415 * This is an incomplete and extremely ugly workaround,
416 * required to let the OpenBSD tree build.
417 */
425 /* FALLTHROUGH */
429 /* FALLTHROUGH */
437 }
439 /*
440 * Default block rewinding rules.
441 * In particular, always skip block end markers,
442 * and let all blocks rewind Nm children.
443 */
449 /*
450 * By default, closing out full blocks
451 * forces closing of broken explicit blocks,
452 * while closing out partial blocks
453 * allows delayed rewinding by default.
454 */
457 }
460 static int
462 {
472 }
475 /*
476 * We are trying to close a block identified by tok,
477 * but the child block *broken is still open.
478 * Thus, postpone closing the tok block
479 * until the rew_sub call closing *broken.
480 */
481 static int
484 {
487 /*
488 * Iterate backwards, searching for the block matching tok,
489 * that is, the block breaking the *broken block.
490 */
493 /*
494 * If the *broken block had already been broken before
495 * and we encounter its breaker, make the tok block
496 * pending on the inner breaker.
497 * Graphically, "[A breaker=[B broken=[C->B B] tok=A] C]"
498 * becomes "[A broken=[B [C->B B] tok=A] C]"
499 * and finally "[A [B->A [C->B B] A] C]".
500 */
504 }
511 /*
512 * Found the breaker.
513 * If another, outer breaker is already pending on
514 * the *broken block, we must not clobber the link
515 * to the outer breaker, but make it pending on the
516 * new, now inner breaker.
517 * Graphically, "[A breaker=[B broken=[C->A A] tok=B] C]"
518 * becomes "[A breaker=[B->A broken=[C A] tok=B] C]"
519 * and finally "[A [B->A [C->B A] B] C]".
520 */
524 /*
525 * If the breaker had also been broken before,
526 * it cannot take on the outer breaker itself,
527 * but must hand it on to its own breakers.
528 * Graphically, this is the following situation:
529 * "[A [B breaker=[C->B B] broken=[D->A A] tok=C] D]"
530 * "[A taker=[B->A breaker=[C->B B] [D->C A] C] D]"
531 */
536 }
542 }
544 /*
545 * Found no matching block for tok.
546 * Are you trying to close a block that is not open?
547 */
549 }
552 static int
555 {
573 /* FALLTHROUGH */
583 /* FALLTHROUGH */
587 }
589 }
595 /*
596 * The current block extends an enclosing block.
597 * Now that the current block ends, close the enclosing block, too.
598 */
605 }
608 }
610 /*
611 * Allocate a word and check whether it's punctuation or not.
612 * Punctuation consists of those tokens found in mdoc_isdelim().
613 */
614 static int
617 {
628 }
636 /*
637 * Closing delimiters only suppress the preceding space
638 * when they follow something, not when they start a new
639 * block or element, and not when they follow `No'.
640 *
641 * XXX Explicitly special-casing MDOC_No here feels
642 * like a layering violation. Find a better way
643 * and solve this in the code related to `No'!
644 */
652 }
654 static int
656 {
675 /*
676 * If we encounter end-of-sentence symbols, then trigger
677 * the double-space.
678 *
679 * XXX: it's easy to allow this to propagate outward to
680 * the last symbol, such that `. )' will cause the
681 * correct double-spacing. However, (1) groff isn't
682 * smart enough to do this and (2) it would require
683 * knowing which symbols break this behaviour, for
684 * example, `. ;' shouldn't propagate the double-space.
685 */
688 }
691 }
694 /*
695 * Close out block partial/full explicit.
696 */
697 static int
699 {
720 }
722 /*
723 * Search backwards for beginnings of blocks,
724 * both of our own and of pending sub-blocks.
725 */
732 /* Remember the start of our own body. */
737 }
744 /*
745 * Found the start of our own block.
746 * When there is no pending sub block,
747 * just proceed to closing out.
748 */
752 /*
753 * When there is a pending sub block,
754 * postpone closing out the current block
755 * until the rew_sub() closing out the sub-block.
756 */
759 /*
760 * Mark the place where the formatting - but not
761 * the scope - of the current block ends.
762 */
767 }
769 /*
770 * When finding an open sub block, remember the last
771 * open explicit block, or, in case there are only
772 * implicit ones, the first open implicit block.
773 */
779 }
782 /* FIXME: do this in validate */
789 }
805 }
823 }
829 }
836 }
844 }
847 static int
849 {
860 /*
861 * Whether we allow ignored elements (those without content,
862 * usually because of reserved words) to squeak by.
863 */
867 /* FALLTHROUGH */
869 /* FALLTHROUGH */
871 /* FALLTHROUGH */
873 /* FALLTHROUGH */
875 /* FALLTHROUGH */
882 }
891 }
899 }
914 /*
915 * In this case, we've located a submacro and must
916 * execute it. Close out scope, if open. If no
917 * elements have been generated, either create one (nc)
918 * or raise a warning.
919 */
933 MANDOCERR_MACROEMPTY);
934 }
941 }
943 /*
944 * Non-quote-enclosed punctuation. Set up our scope, if
945 * a word; rewind the scope, if a delimiter; then append
946 * the word.
947 */
952 /*
953 * If we encounter closing punctuation, no word
954 * has been omitted, no scope is open, and we're
955 * allowed to have an empty element, then start
956 * a new scope. `Ar', `Fl', and `Li', only do
957 * this once per invocation. There may be more
958 * of these (all of them?).
959 */
967 cnt++;
969 }
970 /*
971 * Close out our scope, if one is open, before
972 * any punctuation.
973 */
981 }
984 cnt++;
990 /*
991 * `Fl' macros have their scope re-opened with each new
992 * word so that the `-' can be added to each one without
993 * having to parse out spaces.
994 */
999 }
1000 }
1005 /*
1006 * If no elements have been collected and we're allowed to have
1007 * empties (nc), open a scope and close it out. Otherwise,
1008 * raise a warning.
1009 */
1019 }
1024 }
1027 static int
1029 {
1043 /* Close out prior implicit scope. */
1050 }
1052 /*
1053 * This routine accommodates implicitly- and explicitly-scoped
1054 * macro openings. Implicit ones first close out prior scope
1055 * (seen above). Delay opening the head until necessary to
1056 * allow leading punctuation to print. Special consideration
1057 * for `It -column', which has phrase-part syntax instead of
1058 * regular child nodes.
1059 */
1068 }
1077 }
1084 /*
1085 * Exception: Heads of `It' macros in `-diag' lists are not
1086 * parsed, even though `It' macros in general are parsed.
1087 */
1092 /*
1093 * The `Nd' macro has all arguments in its body: it's a hybrid
1094 * of block partial-explicit and full-implicit. Stupid.
1095 */
1106 }
1115 /* Initialise last-phrase-type with ARGS_PEND. */
1128 /*
1129 * This is necessary: if the last token on a
1130 * line is a `Ta' or tab, then we'll get
1131 * ARGS_EOLN, so we must be smart enough to
1132 * reopen our scope if the last parse was a
1133 * phrase or partial phrase.
1134 */
1141 }
1143 /*
1144 * Emit leading punctuation (i.e., punctuation before
1145 * the MDOC_HEAD) for non-phrase types.
1146 */
1157 }
1159 /* Open a head if one hasn't been opened. */
1165 }
1170 /*
1171 * If we haven't opened a body yet, rewind the
1172 * head; if we have, rewind that instead.
1173 */
1179 /* Then allocate our body context. */
1185 /*
1186 * Process phrases: set whether we're in a
1187 * partial-phrase (this effects line handling)
1188 * then call down into the phrase parser.
1189 */
1201 }
1211 }
1216 }
1222 }
1227 /* If we've already opened our body, exit now. */
1232 /*
1233 * If there is an open (i.e., unvalidated) sub-block requiring
1234 * explicit close-out, postpone switching the current block from
1235 * head to body until the rew_sub() call closing out that
1236 * sub-block.
1237 */
1244 }
1245 }
1247 /* Close out scopes to remain in a consistent state. */
1254 out:
1265 }
1268 static int
1270 {
1281 /*
1282 * A macro that spans to the end of the line. This is generally
1283 * (but not necessarily) called as the first macro. The block
1284 * has a head as the immediate child, which is always empty,
1285 * followed by zero or more opening punctuation nodes, then the
1286 * body (which may be empty, depending on the macro), then zero
1287 * or more closing punctuation nodes.
1288 */
1300 /*
1301 * Open the body scope "on-demand", that is, after we've
1302 * processed all our the leading delimiters (open parenthesis,
1303 * etc.).
1304 */
1322 }
1328 }
1337 }
1342 }
1344 /* Clean-ups to leave in a consistent state. */
1350 }
1355 /*
1356 * End of sentence spacing: if the last node is a text node and
1357 * has a trailing period, then mark it as being end-of-sentence.
1358 */
1364 /* Up-propagate the end-of-space flag. */
1369 }
1371 /*
1372 * If there is an open sub-block requiring explicit close-out,
1373 * postpone closing out the current block
1374 * until the rew_sub() call closing out the sub-block.
1375 */
1386 }
1387 }
1389 /*
1390 * If we can't rewind to our body, then our scope has already
1391 * been closed by another macro (like `Oc' closing `Op'). This
1392 * is ugly behaviour nodding its head to OpenBSD's overwhelming
1393 * crufty use of `Op' breakage.
1394 */
1402 /* Standard appending of delimiters. */
1407 /* Rewind scope, if applicable. */
1412 /* Move trailing .Ns out of scope. */
1420 }
1423 static int
1425 {
1435 /*
1436 * The opening of an explicit macro having zero or more leading
1437 * punctuation nodes; a head with optional single element (the
1438 * case of `Eo'); and a body that may be empty.
1439 */
1455 /* Flush out leading punctuation. */
1463 }
1470 }
1472 /*
1473 * `Eo' gobbles any data into the head, but most other
1474 * macros just immediately close out and begin the body.
1475 */
1479 /* No check whether it's a macro! */
1492 }
1503 }
1508 }
1510 /* Clean-up to leave in a consistent state. */
1521 }
1523 /* Standard appending of delimiters. */
1528 }
1531 /* ARGSUSED */
1532 static int
1534 {
1544 /*
1545 * A line macro that has a fixed number of arguments (maxargs).
1546 * Only open the scope once the first non-leading-punctuation is
1547 * found (unless MDOC_IGNDELIM is noted, like in `Pf'), then
1548 * keep it open until the maximum number of arguments are
1549 * exhausted.
1550 */
1554 /* FALLTHROUGH */
1556 /* FALLTHROUGH */
1558 /* FALLTHROUGH */
1563 /* FALLTHROUGH */
1570 }
1579 }
1588 }
1615 }
1625 j++;
1627 }
1636 }
1641 j++;
1642 }
1647 /* Close out in a consistent state. */
1654 }
1657 static int
1659 {
1672 /* Parse macro arguments. */
1681 }
1689 }
1691 /* Open element scope. */
1696 /* Parse argument terms. */
1714 }
1719 }
1721 /* Close out (no delimiters). */
1724 }
1727 /* ARGSUSED */
1728 static int
1730 {
1735 /* If we're not in the SYNOPSIS, go straight to in-line. */
1739 /* If we're a nested call, same place. */
1743 /*
1744 * XXX: this will open a block scope; however, if later we end
1745 * up formatting the block scope, then child nodes will inherit
1746 * the formatting. Be careful.
1747 */
1752 }
1755 /* ARGSUSED */
1756 static int
1758 {
1762 }
1765 /*
1766 * Phrases occur within `Bl -column' entries, separated by `Ta' or tabs.
1767 * They're unusual because they're basically free-form text until a
1768 * macro is encountered.
1769 */
1770 static int
1772 {
1794 }
1799 }
1802 }
1805 /* ARGSUSED */
1806 static int
1808 {
1815 /* Make sure we are in a column list or ignore this macro. */
1822 }
1824 /* Advance to the next column. */
1846 }
1851 }
1854 }