Reference Documentation: PDF Publishing with GNU Troff
Revision | e508edf7e839fc34c4790a0137a648341ba64d16 (tree) |
---|---|
Time | 2023-05-14 00:27:28 |
Author | Keith Marshall <keith@user...> |
Commiter | Keith Marshall |
Describe method of finished document assembly.
* pdfmark.ms (Section 4.1.7): Add content.
(Section 4.1.4): Omit "$" prompt from "pdfroff" command example,
to maintain consistency with all earlier, and new examples.
@@ -6862,7 +6862,7 @@ | ||
6862 | 6862 | in the form: |
6863 | 6863 | .DS I |
6864 | 6864 | .CW |
6865 | -$ pdfroff -mspdf --stylesheet=cover.ms pdfmark.ms > pdfmark.pdf | |
6865 | +pdfroff -mspdf --stylesheet=cover.ms pdfmark.ms > pdfmark.pdf | |
6866 | 6866 | .DE |
6867 | 6867 | This causes |
6868 | 6868 | .CW pdfroff |
@@ -7884,6 +7884,189 @@ | ||
7884 | 7884 | . |
7885 | 7885 | .NH 3 |
7886 | 7886 | .XN -S -N document-assembly -- How \F[C]pdfroff\F[] Assembles a Finished Document |
7887 | +.LP | |
7888 | +After | |
7889 | +.CW pdfroff | |
7890 | +has completed each of the processing phases, | |
7891 | +enumerated as phase\~no.\|1 to phase\~no.\|5 in | |
7892 | +.XR-NO-PREFIX pdfroff-operation , | |
7893 | +.EM "at least one" , | |
7894 | +and | |
7895 | +.EM "at most three" | |
7896 | +intermediate \*[PostScript] output files will have been created, | |
7897 | +(in addition to the temporary files designated by the | |
7898 | +.CW WRKFILE , | |
7899 | +.CW REFFILE , | |
7900 | +and | |
7901 | +.CW REFCOPY | |
7902 | +shell variables). | |
7903 | +If only one intermediate output file is created, it | |
7904 | +.EM must | |
7905 | +be the document body component; | |
7906 | +if more than one such file is created, one | |
7907 | +.EM must | |
7908 | +be the document body component, | |
7909 | +while any others may be | |
7910 | +.EM "either one" | |
7911 | +of, or | |
7912 | +.EM both | |
7913 | +of a \%front\(hymatter component, | |
7914 | +and a table of contents component. | |
7915 | +In this final phase of | |
7916 | +.CW pdfroff | |
7917 | +processing, | |
7918 | +the entire complement of created intermediate output files is conjoined, | |
7919 | +in the order: | |
7920 | +.QS | |
7921 | +.sp -\n[PD]u | |
7922 | +.IP \(bu 2n | |
7923 | +\%Front\(hymatter component (if present); | |
7924 | +.IP \(bu | |
7925 | +Table of contents component (if present); | |
7926 | +.IP \(bu | |
7927 | +Document body component | |
7928 | +.QE | |
7929 | +to assemble the finished output document, | |
7930 | +either merging all component content into a single \*[PostScript] document, | |
7931 | +(if the | |
7932 | +.CW \%\-\-emit\-ps | |
7933 | +option has been specified), | |
7934 | +or normally, | |
7935 | +merging all content, | |
7936 | +and simultaneously converting to PDF. | |
7937 | +. | |
7938 | +.LP | |
7939 | +Depending on the particular complement | |
7940 | +of intermediate output files which have been created, | |
7941 | +document assembly proceeds as follows: | |
7942 | +.QS | |
7943 | +.sp -\n[PD]u | |
7944 | +.IP \(bu 2n | |
7945 | +If a \%front\(hymatter intermediate output file has been created, | |
7946 | +its content is simply copied, without change, | |
7947 | +to the beginning of the final output file. | |
7948 | +. | |
7949 | +.IP \(bu | |
7950 | +As has been noted previously, in | |
7951 | +.XR-NO-PREFIX toc-generation , | |
7952 | +if a table of contents intermediate output file has been created, | |
7953 | +it | |
7954 | +.EM will | |
7955 | +contain the formatted table of contents, | |
7956 | +but this will be preceded by a sequence of blank pages, | |
7957 | +with one blank page for each page in the document body; | |
7958 | +these blank pages will (usually) not be wanted in the finished document, | |
7959 | +so, before merging this intermediate file content, | |
7960 | +it is passed through a | |
7961 | +.CW sed | |
7962 | +filter, | |
7963 | +to remove them; | |
7964 | +the residual comtent is then copied into the final output file, | |
7965 | +either following the \%front\(hymatter, if present, | |
7966 | +or otherwise, at its beginning. | |
7967 | +. | |
7968 | +.IP \(bu | |
7969 | +Finally, | |
7970 | +the content of the document body is read | |
7971 | +from its respective intermediate output file, | |
7972 | +and merged into the final output file, | |
7973 | +following any content which had previously been merged | |
7974 | +from \%front\(hymatter and table of contents intermediate output files; | |
7975 | +as in the case of table of contents intermediate output, | |
7976 | +this document body output is also passed, by default, | |
7977 | +through the same blank page removal | |
7978 | +.CW sed | |
7979 | +filter. | |
7980 | +.QE | |
7981 | +It may be observed that, | |
7982 | +by default, | |
7983 | +.CW pdfroff | |
7984 | +will filter | |
7985 | +.EM both | |
7986 | +the table of contents intermediate output, if any, | |
7987 | +and the document body intermediate output, | |
7988 | +to remove blank pages. | |
7989 | +While the intent of this is to discard | |
7990 | +.EM phantom | |
7991 | +blank pages, | |
7992 | +which precede the actual table of contents, | |
7993 | +and which follow the document body, | |
7994 | +it must be understood that it will actually remove | |
7995 | +.EM all | |
7996 | +blank pages\*[em]\c | |
7997 | +.EM both | |
7998 | +those which promote this intent, | |
7999 | +.EM and | |
8000 | +any others which may appear | |
8001 | +.EM within | |
8002 | +the table of contents, | |
8003 | +and the document body. | |
8004 | +This may, or may not, be desireable behaviour\*[em]it probably | |
8005 | +.EM is , | |
8006 | +within the table of contents, | |
8007 | +but is less so within the document body, | |
8008 | +especially if the trailing blank pages, | |
8009 | +resulting from \%\(lqpen\(hyup\(rq formatting | |
8010 | +of an appended table of contents, | |
8011 | +have been optimized out, | |
8012 | +as suggested in | |
8013 | +.XR-NO-PREFIX body-formatting . | |
8014 | +. | |
8015 | +.LP | |
8016 | +Some control of blank page removal | |
8017 | +may be achieved by specification of the | |
8018 | +.CW \%\-\-no\-kill\-null\-pages | |
8019 | +option\*[em]or | |
8020 | +.CW \%\-\-no\-kill\-null\-pages[=< \c | |
8021 | +.CWI whence >] \& , | |
8022 | +from the | |
8023 | +.CW \%groff-pdfmark-20230406.1 | |
8024 | +release onwards\*[em]on the | |
8025 | +.CW pdfroff | |
8026 | +command line, or alternatively, | |
8027 | +and once again, only from the release of | |
8028 | +.CW \%groff-pdfmark-20230406.1 | |
8029 | +onwards, | |
8030 | +by use of the | |
8031 | +.CW \%preserve_blank_pages=< \c | |
8032 | +.CWI whence > | |
8033 | +\%in\(hydocument hint. | |
8034 | +When supported, the | |
8035 | +.CWI whence > < | |
8036 | +argument may take a value of | |
8037 | +.CW toc \(rq, \(lq | |
8038 | +.CW body \(rq, \(lq | |
8039 | +or | |
8040 | +.CW all \(rq, \(lq | |
8041 | +with | |
8042 | +.CW all \(rq \(lq | |
8043 | +being the default, | |
8044 | +and equivalent to the original behaviour; | |
8045 | +its effect is to suppress removal of | |
8046 | +.EM all | |
8047 | +blank pages originating from the | |
8048 | +table of contents intermediate output file, | |
8049 | +.EM and | |
8050 | +from the document body intermediate output, | |
8051 | +which is probably not the desired effect. | |
8052 | +More useful behaviour may be to retain the default | |
8053 | +removal of blank pages originating from | |
8054 | +the table of contents intermediate output, | |
8055 | +while suppressing it for those originating within the document body; | |
8056 | +this may be achieved by invoking | |
8057 | +.CW pdfroff | |
8058 | +with a command such as: | |
8059 | +.QS | |
8060 | +.CW "pdfroff --no-kill-blank-pages=body ..." | |
8061 | +.QE | |
8062 | +or by including the equivalent \%in\(hydocument hint: | |
8063 | +.QS | |
8064 | +.CW ".pdfroff option preserve_blank_pages=body" | |
8065 | +.QE | |
8066 | +within the document source file, | |
8067 | +(perhaps making it conditional on some appropriate condition, | |
8068 | +such as selection of a duplex printing configuration, | |
8069 | +for example). | |
7887 | 8070 | . |
7888 | 8071 | .NH 2 |
7889 | 8072 | .XN -N do-xref -- Further Considerations for Using Document References |