| blob | 98a18a386317d51c2ecc84672bf793f5babf9179 |
1 /* $Vendor-Id: mdoc_macro.c,v 1.115 2012/01/05 00:43:51 schwarze Exp $ */
2 /*
3 * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 * Copyright (c) 2010 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 };
195 };
200 /*
201 * This is called at the end of parsing. It must traverse up the tree,
202 * closing out open [implicit] scopes. Obviously, open explicit scopes
203 * are errors.
204 */
205 int
207 {
210 /* Scan for open explicit scopes. */
219 /* Rewind to the first. */
222 }
225 /*
226 * Look up a macro from within a subsequent context.
227 */
228 static enum mdoct
230 {
235 }
238 /*
239 * Lookup a macro following the initial line macro.
240 */
241 static enum mdoct
243 {
251 }
254 static int
256 {
262 /* LINTED */
264 /*
265 * Save the parent here, because we may delete the
266 * m->last node in the post-validation phase and reset
267 * it to m->last->parent, causing a step in the closing
268 * out to be lost.
269 */
277 }
280 }
283 /*
284 * For a block closing macro, return the corresponding opening one.
285 * Otherwise, return the macro itself.
286 */
287 static enum mdoct
289 {
325 }
326 /* NOTREACHED */
327 }
330 /*
331 * Rewinding to tok, how do we have to handle *p?
332 * REWIND_NONE: *p would delimit tok, but no tok scope is open
333 * inside *p, so there is no need to rewind anything at all.
334 * REWIND_THIS: *p matches tok, so rewind *p and nothing else.
335 * REWIND_MORE: *p is implicit, rewind it and keep searching for tok.
336 * REWIND_FORCE: *p is explicit, but tok is full, force rewinding *p.
337 * REWIND_LATER: *p is explicit and still open, postpone rewinding.
338 * REWIND_ERROR: No tok block is open at all.
339 */
340 static enum rew
343 {
345 /*
346 * No matching token, no delimiting block, no broken block.
347 * This can happen when full implicit macros are called for
348 * the first time but try to rewind their previous
349 * instance anyway.
350 */
356 /*
357 * When starting to rewind, skip plain text
358 * and nodes that have already been rewound.
359 */
363 /*
364 * The easiest case: Found a matching token.
365 * This applies to both blocks and elements.
366 */
372 /*
373 * While elements do require rewinding for themselves,
374 * they never affect rewinding of other nodes.
375 */
379 /*
380 * Blocks delimited by our target token get REWIND_MORE.
381 * Blocks delimiting our target token get REWIND_NONE.
382 */
392 /*
393 * XXX Badly nested block handling still fails badly
394 * when one block is breaking two blocks of the same type.
395 * This is an incomplete and extremely ugly workaround,
396 * required to let the OpenBSD tree build.
397 */
405 /* FALLTHROUGH */
409 /* FALLTHROUGH */
417 }
419 /*
420 * Default block rewinding rules.
421 * In particular, always skip block end markers,
422 * and let all blocks rewind Nm children.
423 */
429 /*
430 * By default, closing out full blocks
431 * forces closing of broken explicit blocks,
432 * while closing out partial blocks
433 * allows delayed rewinding by default.
434 */
437 }
440 static int
442 {
452 }
455 /*
456 * We are trying to close a block identified by tok,
457 * but the child block *broken is still open.
458 * Thus, postpone closing the tok block
459 * until the rew_sub call closing *broken.
460 */
461 static int
464 {
467 /*
468 * Iterate backwards, searching for the block matching tok,
469 * that is, the block breaking the *broken block.
470 */
473 /*
474 * If the *broken block had already been broken before
475 * and we encounter its breaker, make the tok block
476 * pending on the inner breaker.
477 * Graphically, "[A breaker=[B broken=[C->B B] tok=A] C]"
478 * becomes "[A broken=[B [C->B B] tok=A] C]"
479 * and finally "[A [B->A [C->B B] A] C]".
480 */
484 }
491 /*
492 * Found the breaker.
493 * If another, outer breaker is already pending on
494 * the *broken block, we must not clobber the link
495 * to the outer breaker, but make it pending on the
496 * new, now inner breaker.
497 * Graphically, "[A breaker=[B broken=[C->A A] tok=B] C]"
498 * becomes "[A breaker=[B->A broken=[C A] tok=B] C]"
499 * and finally "[A [B->A [C->B A] B] C]".
500 */
504 /*
505 * If the breaker had also been broken before,
506 * it cannot take on the outer breaker itself,
507 * but must hand it on to its own breakers.
508 * Graphically, this is the following situation:
509 * "[A [B breaker=[C->B B] broken=[D->A A] tok=C] D]"
510 * "[A taker=[B->A breaker=[C->B B] [D->C A] C] D]"
511 */
516 }
522 }
524 /*
525 * Found no matching block for tok.
526 * Are you trying to close a block that is not open?
527 */
529 }
532 static int
535 {
550 /* FALLTHROUGH */
558 /* FALLTHROUGH */
562 }
564 }
570 /*
571 * The current block extends an enclosing block.
572 * Now that the current block ends, close the enclosing block, too.
573 */
580 }
583 }
585 /*
586 * Allocate a word and check whether it's punctuation or not.
587 * Punctuation consists of those tokens found in mdoc_isdelim().
588 */
589 static int
592 {
603 /*
604 * Closing delimiters only suppress the preceding space
605 * when they follow something, not when they start a new
606 * block or element, and not when they follow `No'.
607 *
608 * XXX Explicitly special-casing MDOC_No here feels
609 * like a layering violation. Find a better way
610 * and solve this in the code related to `No'!
611 */
618 }
620 static int
622 {
641 /*
642 * If we encounter end-of-sentence symbols, then trigger
643 * the double-space.
644 *
645 * XXX: it's easy to allow this to propagate outward to
646 * the last symbol, such that `. )' will cause the
647 * correct double-spacing. However, (1) groff isn't
648 * smart enough to do this and (2) it would require
649 * knowing which symbols break this behaviour, for
650 * example, `. ;' shouldn't propagate the double-space.
651 */
654 }
657 }
660 /*
661 * Close out block partial/full explicit.
662 */
663 static int
665 {
684 }
686 /*
687 * Search backwards for beginnings of blocks,
688 * both of our own and of pending sub-blocks.
689 */
696 /* Remember the start of our own body. */
701 }
708 /*
709 * Found the start of our own block.
710 * When there is no pending sub block,
711 * just proceed to closing out.
712 */
716 /*
717 * When there is a pending sub block,
718 * postpone closing out the current block
719 * until the rew_sub() closing out the sub-block.
720 */
723 /*
724 * Mark the place where the formatting - but not
725 * the scope - of the current block ends.
726 */
731 }
733 /*
734 * When finding an open sub block, remember the last
735 * open explicit block, or, in case there are only
736 * implicit ones, the first open implicit block.
737 */
743 }
746 /* FIXME: do this in validate */
753 }
769 }
786 }
792 }
796 }
804 }
807 static int
809 {
820 /*
821 * Whether we allow ignored elements (those without content,
822 * usually because of reserved words) to squeak by.
823 */
827 /* FALLTHROUGH */
829 /* FALLTHROUGH */
831 /* FALLTHROUGH */
833 /* FALLTHROUGH */
835 /* FALLTHROUGH */
842 }
851 }
859 }
874 /*
875 * In this case, we've located a submacro and must
876 * execute it. Close out scope, if open. If no
877 * elements have been generated, either create one (nc)
878 * or raise a warning.
879 */
892 }
899 }
901 /*
902 * Non-quote-enclosed punctuation. Set up our scope, if
903 * a word; rewind the scope, if a delimiter; then append
904 * the word.
905 */
910 /*
911 * If we encounter closing punctuation, no word
912 * has been omitted, no scope is open, and we're
913 * allowed to have an empty element, then start
914 * a new scope. `Ar', `Fl', and `Li', only do
915 * this once per invocation. There may be more
916 * of these (all of them?).
917 */
924 cnt++;
926 }
927 /*
928 * Close out our scope, if one is open, before
929 * any punctuation.
930 */
938 }
941 cnt++;
946 /*
947 * `Fl' macros have their scope re-opened with each new
948 * word so that the `-' can be added to each one without
949 * having to parse out spaces.
950 */
955 }
956 }
961 /*
962 * If no elements have been collected and we're allowed to have
963 * empties (nc), open a scope and close it out. Otherwise,
964 * raise a warning.
965 */
975 }
980 }
983 static int
985 {
999 /* Close out prior implicit scope. */
1006 }
1008 /*
1009 * This routine accommodates implicitly- and explicitly-scoped
1010 * macro openings. Implicit ones first close out prior scope
1011 * (seen above). Delay opening the head until necessary to
1012 * allow leading punctuation to print. Special consideration
1013 * for `It -column', which has phrase-part syntax instead of
1014 * regular child nodes.
1015 */
1024 }
1033 }
1040 /*
1041 * Exception: Heads of `It' macros in `-diag' lists are not
1042 * parsed, even though `It' macros in general are parsed.
1043 */
1048 /*
1049 * The `Nd' macro has all arguments in its body: it's a hybrid
1050 * of block partial-explicit and full-implicit. Stupid.
1051 */
1062 }
1068 /* Initialise last-phrase-type with ARGS_PEND. */
1081 /*
1082 * This is necessary: if the last token on a
1083 * line is a `Ta' or tab, then we'll get
1084 * ARGS_EOLN, so we must be smart enough to
1085 * reopen our scope if the last parse was a
1086 * phrase or partial phrase.
1087 */
1094 }
1096 /*
1097 * Emit leading punctuation (i.e., punctuation before
1098 * the MDOC_HEAD) for non-phrase types.
1099 */
1110 }
1112 /* Open a head if one hasn't been opened. */
1118 }
1123 /*
1124 * If we haven't opened a body yet, rewind the
1125 * head; if we have, rewind that instead.
1126 */
1132 /* Then allocate our body context. */
1138 /*
1139 * Process phrases: set whether we're in a
1140 * partial-phrase (this effects line handling)
1141 * then call down into the phrase parser.
1142 */
1154 }
1163 }
1168 }
1174 }
1179 /* If we've already opened our body, exit now. */
1184 /*
1185 * If there is an open (i.e., unvalidated) sub-block requiring
1186 * explicit close-out, postpone switching the current block from
1187 * head to body until the rew_sub() call closing out that
1188 * sub-block.
1189 */
1196 }
1197 }
1199 /* Close out scopes to remain in a consistent state. */
1206 out:
1217 }
1220 static int
1222 {
1233 /*
1234 * A macro that spans to the end of the line. This is generally
1235 * (but not necessarily) called as the first macro. The block
1236 * has a head as the immediate child, which is always empty,
1237 * followed by zero or more opening punctuation nodes, then the
1238 * body (which may be empty, depending on the macro), then zero
1239 * or more closing punctuation nodes.
1240 */
1252 /*
1253 * Open the body scope "on-demand", that is, after we've
1254 * processed all our the leading delimiters (open parenthesis,
1255 * etc.).
1256 */
1274 }
1280 }
1288 }
1293 }
1295 /* Clean-ups to leave in a consistent state. */
1301 }
1306 /*
1307 * End of sentence spacing: if the last node is a text node and
1308 * has a trailing period, then mark it as being end-of-sentence.
1309 */
1315 /* Up-propagate the end-of-space flag. */
1320 }
1322 /*
1323 * If there is an open sub-block requiring explicit close-out,
1324 * postpone closing out the current block
1325 * until the rew_sub() call closing out the sub-block.
1326 */
1336 }
1337 }
1339 /*
1340 * If we can't rewind to our body, then our scope has already
1341 * been closed by another macro (like `Oc' closing `Op'). This
1342 * is ugly behaviour nodding its head to OpenBSD's overwhelming
1343 * crufty use of `Op' breakage.
1344 */
1352 /* Standard appending of delimiters. */
1357 /* Rewind scope, if applicable. */
1363 }
1366 static int
1368 {
1378 /*
1379 * The opening of an explicit macro having zero or more leading
1380 * punctuation nodes; a head with optional single element (the
1381 * case of `Eo'); and a body that may be empty.
1382 */
1398 /* Flush out leading punctuation. */
1406 }
1413 }
1415 /*
1416 * `Eo' gobbles any data into the head, but most other
1417 * macros just immediately close out and begin the body.
1418 */
1422 /* No check whether it's a macro! */
1435 }
1445 }
1450 }
1452 /* Clean-up to leave in a consistent state. */
1463 }
1465 /* Standard appending of delimiters. */
1470 }
1473 /* ARGSUSED */
1474 static int
1476 {
1486 /*
1487 * A line macro that has a fixed number of arguments (maxargs).
1488 * Only open the scope once the first non-leading-punctuation is
1489 * found (unless MDOC_IGNDELIM is noted, like in `Pf'), then
1490 * keep it open until the maximum number of arguments are
1491 * exhausted.
1492 */
1496 /* FALLTHROUGH */
1498 /* FALLTHROUGH */
1500 /* FALLTHROUGH */
1505 /* FALLTHROUGH */
1512 }
1521 }
1530 }
1557 }
1567 j++;
1569 }
1578 }
1582 j++;
1583 }
1588 /* Close out in a consistent state. */
1595 }
1598 static int
1600 {
1613 /* Parse macro arguments. */
1622 }
1630 }
1632 /* Open element scope. */
1637 /* Parse argument terms. */
1654 }
1659 }
1661 /* Close out (no delimiters). */
1664 }
1667 /* ARGSUSED */
1668 static int
1670 {
1675 /* If we're not in the SYNOPSIS, go straight to in-line. */
1679 /* If we're a nested call, same place. */
1683 /*
1684 * XXX: this will open a block scope; however, if later we end
1685 * up formatting the block scope, then child nodes will inherit
1686 * the formatting. Be careful.
1687 */
1692 }
1695 /* ARGSUSED */
1696 static int
1698 {
1702 }
1705 /*
1706 * Phrases occur within `Bl -column' entries, separated by `Ta' or tabs.
1707 * They're unusual because they're basically free-form text until a
1708 * macro is encountered.
1709 */
1710 static int
1712 {
1734 }
1739 }
1742 }
1745 /* ARGSUSED */
1746 static int
1748 {
1754 /*
1755 * FIXME: this is overly restrictive: if the `Ta' is unexpected,
1756 * it should simply error out with ARGSLOST.
1757 */
1779 }
1784 }
1787 }