• R/O
  • SSH

提交

標籤
無標籤

Frequently used words (click to add to your profile)

javac++androidlinuxc#objective-cqt誰得cocoawindowspythonrubyphpgameguibathyscaphec翻訳omegat計画中(planning stage)frameworktwittertestdombtronvb.netdirectxarduinopreviewerゲームエンジン

Reference Documentation: PDF Publishing with GNU Troff


Commit MetaInfo

修訂aae8df304ce076a1d29d96bf6ef888f95ff3d88d (tree)
時間2022-03-02 00:15:26
作者Keith Marshall <keith@user...>
CommiterKeith Marshall

Log Message

Document "ms" section headings support features.

* pdfmark.ms (Section 3.1.2): Update and expand; refer to...
(XH, XN): ...this pair of section heading specification macros.
(Subsection 3.1.2.1): Add content to document them.
(Subsection 3.1.2.2): Add content; document...
(XH-INIT, XN-INIT): ...this pair of user-definable macros.
(Subsection 3.1.2.3): Add content; document...
(XH-UPDATE-TOC): ...this user-redefinable macro.
(Subsection 3.1.2.4): Add content; document...
(XH-REPLACEMENT, XN-REPLACEMENT): ...these user-redefinable macros.

* tmac/spdf.tmac (XN): Correct comment typo; should refer to...
(NH <n>): ...this, rather than implied use after self.

Change Summary

差異

diff -r 651fc10b18c4 -r aae8df304ce0 pdfmark.ms
--- a/pdfmark.ms Sun Feb 27 14:19:43 2022 +0000
+++ b/pdfmark.ms Tue Mar 01 15:15:26 2022 +0000
@@ -4028,7 +4028,7 @@
40284028 .QE
40294029 .
40304030 .NH 3
4031-.XN -S -- \F[C]ms\F[] Section Headings in PDF Documents
4031+.XN -S -- Using \F[C]ms\F[] Section Headings in PDF Documents
40324032 .LP
40334033 Traditionally,
40344034 .CW ms
@@ -4036,29 +4036,561 @@
40364036 .CW NH
40374037 and
40384038 .CW SH
4039-macros, to specify section headings.
4039+macros to introduce section headings.
40404040 However,
4041+in traditional
4042+.CW ms
4043+implementations,
40414044 there is no standard mechanism for generating a
40424045 table of contents entry based on the text of the section heading;
4043-neither is there any recognized standard method for establishing a
4044-cross reference link to the section.
4046+neither is there any recognized standard method
4047+for establishing a cross reference link,
4048+or a document outline reference,
4049+to the section.
40454050 .LP
4046-To address this
4051+To address this limitation of traditional
40474052 .CW ms
4048-limitation,
4053+implementations,
4054+the
40494055 .CW spdf.tmac
4050-defines the
4056+binding macro package provides the
4057+.CW XH
4058+and
4059+.CW XN
4060+macros\Z','\**
4061+.FS
4062+On a technical note,
4063+since
4064+.CW \%groff-1.23 ,
4065+the
4066+.CW groff
4067+implementation of
4068+.CW ms
4069+itself has incorporated basic infrastructure providing
4070+.CW XH
4071+and
4072+.CW XN
4073+macros,
4074+to facilitate duplication of section heading text
4075+into the table of contents;
4076+.CW spdf.tmac
4077+builds on top of this infrastructure,
4078+.EM indirectly
4079+redefining
4080+.CW XH
4081+and
4082+.CW XN ,
4083+by provision of macros
4084+.CW \%XH-REPLACEMENT
4085+and
4086+.CW \%XN-REPLACEMENT
4087+respectively,
4088+to accommodate the duplication of section heading text
4089+into the PDF document outline,
4090+in addition to the table of contents.
4091+Use of this indirect technique is recommended,
4092+whenever redefinition of
4093+.CW XH ,
4094+or
4095+.CW XN ,
4096+is desired.
4097+.FE
4098+.XR xh-xn-macros ), (
4099+to be used in conjunction with the
4100+.CW SH
4101+and
4102+.CW NH
4103+macros respectively;
4104+each of these identifies,
4105+by specification of appropriate arguments,
4106+text which is to be incorporated into the section heading,
4107+duplicated within the PDF document outline,
4108+and in the table of contents.
4109+.
4110+.NH 4
4111+.XN -S -N xh-xn-macros -- The \F[C]XH\F[] and \F[C]XN\F[] Macros
4112+.LP
4113+Formalized from the release of
4114+.CW \%groff-1.23
4115+onwards\Z','\**
4116+.FS
4117+Prior to the release of
4118+.CW \%groff-1.23 ,
4119+a prototypical implementation of
4120+.CW spdf.tmac
4121+was introduced with
4122+.CW \%groff-1.19.2 ;
4123+this prototype included an implementation of the
40514124 .CW XN
40524125 macro,
4053-.XR xn-macro ), (
4054-to be used in conjunction with the
4126+but it did
4127+.EM not
4128+provide
4129+.CW XH ,
4130+nor did it support the
4131+.CW \%XH-INIT ,
4132+.CW \%XN-INIT ,
4133+and
4134+.CW \%XH-UPDATE-TOC
4135+\%call\(hyback features,
4136+nor the
4137+.CW \%XH-REPLACEMENT ,
4138+and
4139+.CW \%XN-REPLACEMENT
4140+capabilities.
4141+.FE
4142+and nominally intended to be used following
4143+.CW SH
4144+and
40554145 .CW NH
4056-macro.
4146+respectively,
4147+the calling syntax for this pair of
4148+.CW spdf.tmac
4149+macros is specified as:\(en
4150+.DS I
4151+.sp -\n(PDu
4152+.CWB .SH
4153+.CWB .XH \& \& \0\c
4154+.CWB -N \& [ \ \c
4155+.CWI name >] < \ \c
4156+.CWB -S ] [ \ \c
4157+.CWB -X ] [ \0\c
4158+.CWI outline-level > < \0\c
4159+.CWI heading-text > < \ \c
4160+.CW ...
4161+.DE
4162+.DS I
4163+.sp -\n(PDu
4164+.CWB .NH \& \& \0\c
4165+.CWI outline-level > <
4166+.CWB .XN \& \& \0\c
4167+.CWB -N \& [ \ \c
4168+.CWI name >] < \ \c
4169+.CWB -S ] [ \ \c
4170+.CWB -X ] [ \0\c
4171+.CWI heading-text > < \ \c
4172+.CW ...
4173+.DE
4174+.LP
4175+.sp -\n(PDu
4176+In either case,
4177+the
4178+.CWI heading-text >... < \&
4179+arguments are incorporated into the document body,
4180+formatted as section heading text.
4181+Additionally,
4182+these same
4183+.CWI heading-text >... < \&
4184+arguments,
4185+(prefixed by the content of the
4186+.CW SN
4187+string,
4188+in the
4189+.CW XN
4190+case),
4191+are incorporated into the PDF document outline,
4192+at the level specified by the
4193+.CWI outline-level > <
4194+argument,
4195+and they are made available to the \%user\(hydefinable
4196+.CW \%XH-UPDATE-TOC
4197+\%call\(hyback macro,
4198+.XR xh-update-toc-macro ), (
4199+to support creation of a corresponding entry in
4200+the document's table of contents.
4201+.LP
4202+In both cases,
4203+the supported macro options\**
4204+.FS
4205+.EM None
4206+of these options are supported by the underlying
4207+.CW ms
4208+implementations of
4209+.CW XH
4210+or
4211+.CW XN ,
4212+as implemented from
4213+.CW \%groff-1.23
4214+onwards.
4215+Prior to
4216+.CW \%groff-1.23 ,
4217+only the
4218+.CW -N \ \c
4219+.CWI name > <
4220+and
4221+.CW -X
4222+options are supported by the prototypical
4223+.CW spdf.tmac
4224+implementation of
4225+.CW XN ,
4226+as provided from
4227+.CW \%groff-1.19.2
4228+onwards.
4229+.FE
4230+are:\(en
4231+.QS
4232+.sp -\n(PDu
4233+.IP "\f(CB-N\fP \FC<\fIname\fP>\F[]"
4234+Create a
4235+.CW pdfhref
4236+destination,
4237+with the specified
4238+.CWI name > < ,
4239+and associate it with the corresponding section heading,
4240+as designated by
4241+.CWI heading-text > \%< .
4242+.IP \*[= -S]
4243+Strip any \%font\(hyfamily selection escape sequences,
4244+which may have been specified,
4245+from a copy of
4246+.CWI heading-text > \%< ,
4247+before incorporating this into the document outline;
4248+(this is necessary when such escape sequences are present,
4249+to avoid verbatim rendition of the escape sequences themselves,
4250+within the text of the document outline).
4251+.IP \*[= -X]
4252+Ensure that any
4253+.CW pdfhref
4254+destination name,
4255+specified by the
4256+.CWB -N
4257+.CWI name > <
4258+option,
4259+is included within the document's \%cross\(hyreference dictionary.
4260+.QE
40574261 .
40584262 .NH 4
4059-.XN -S -N xn-macro -- The \F[C]XN\F[] Macro
4263+.XN -S -N xh-xn-init-macros -- The \F[C]XH\-INIT\F[] and \F[C]XN\-INIT\F[] Macros
4264+.LP
4265+This pair of macros serve as context initialization hooks;
4266+called by the default implementations of the
4267+.CW XH
4268+and
4269+.CW XN
4270+macros respectively,
4271+without arguments,
4272+.EM before
4273+.CW \%XH\-UPDATE\-TOC
4274+is called.
4275+By default,
4276+both return immediately,
4277+.EM without
4278+performing
4279+.EM any
4280+action.
4281+However,
4282+users may override either,
4283+or both,
4284+to perform any desired activity\ ...\ e.g. to save context
4285+for subsequent use by any user\(hydefined macro,
4286+which may have been provided to override the default implementation of
4287+.CW \%XH\-UPDATE\-TOC .
4288+.
4289+.NH 4
4290+.XN -S -N xh-update-toc-macro -- The \F[C]XH\-UPDATE\-TOC\F[] Macro
4291+.LP
4292+This macro is called by both
4293+.CW XH
4294+and
4295+.CW XN ,
4296+(there is no corresponding
4297+.CW \%XN\-UPDATE\-TOC
4298+equivalent,
4299+since none is required to support the default
4300+.CW XH
4301+and
4302+.CW XN
4303+implementations),
4304+to propagate content from the specified section heading arguments
4305+to the document's table of contents.
4306+From
4307+.CW \%groff\-1.23
4308+onwards,
4309+a rudimentary default implementation of
4310+.CW \%XH\-UPDATE\-TOC
4311+is provided within the standard
4312+.CW ms
4313+macro suite;
4314+however,
4315+it is anticipated that the user will override this default implementation,
4316+in order to achieve more effective control of table of contents formatting.
4317+.LP
4318+When writing a replacement for the
4319+.CW \%XH\-UPDATE\-TOC
4320+macro,
4321+it should be implemented such that it will interpret arguments
4322+as specified in the prototype
4323+.DS I
4324+.CWB \%.XH\-UPDATE\-TOC\c
4325+.CWI outline\-level > \ \%< \c
4326+.CWI section\-number >] \ \%[< \c
4327+.CWI heading\-text > \ \%< \ \c
4328+.CWI ...
4329+.DE
4330+in which the
4331+.CWI outline\-level > \%<
4332+and
4333+.CWI heading\-text > \%<
4334+arguments are the same as those specified for the
4335+.CW XH ,
4336+or the
4337+.CW NH \^/\^\c
4338+.CW XN
4339+call sequence,
4340+from which
4341+.CW \%XH\-UPDATE\-TOC
4342+itself is called;
4343+the
4344+.CWI section\-number > \%<
4345+argument is
4346+.EM always
4347+specified,
4348+when
4349+.CW \%XH\-UPDATE\-TOC
4350+is called by
4351+.CW XN ,
4352+(and
4353+.EM never
4354+when called by
4355+.CW XH );
4356+when present,
4357+it represents the value of the
4358+.CW SN
4359+string,
4360+which prevails at the time of the invoking
4361+.CW XN
4362+call,
4363+and is simply processed as a prefix to the
4364+.CWI heading\-text > \%<
4365+argument.
4366+.LP
4367+The default implementation of
4368+.CW \%XH\-UPDATE\-TOC
4369+offers only rudimentary formatting of
4370+the resultant table of contents entry;
4371+the
4372+.CWI outline\-level > \%<
4373+argument is simply ignored,
4374+and the remaining arguments are passed to the standard
4375+.CW ms
4376+table of contents generating capability,
4377+in a form which is equivalent to
4378+.DS I
4379+.CW .XS
4380+.CWI section\-number >\ ] \(rs&[< \c
4381+.CWI heading\-text >\ ... \%<
4382+.CW .XE
4383+.DE
4384+As an example (with abridged comments) of how
4385+.CW \%XH\-UPDATE\-TOC
4386+may be redefined,
4387+to achieve more creative formatting of a table of contents,
4388+this publication substitutes the following document\(hylocal
4389+implementation:
4390+.DS I
4391+.CW
4392+\&.ds XNVS1 0.50v \(rs" leading for top level
4393+\&.ds XNVS2 0.15v \(rs" leading at nesting level increment
4394+\&.ds XNVS3 0.30v \(rs" leading following nested group
4395+\&.
4396+\&.de XH-UPDATE-TOC
4397+\&. XS
4398+\&. if r tc*hl \(rs{\(rs
4399+\&. \(rs" Compute additional leading at <outline-level> change
4400+\&. \(rs"
4401+\&. ie \(rs\(rs$1>1 \(rs{\(rs
4402+\&. ie \(rs\(rs$1>\(rs\(rsn[tc*hl] .sp \(rs\(rs*[XNVS2]
4403+\&. el .if \(rs\(rsn[tc*hl]>\(rs\(rs$1 .sp \(rs\(rs*[XNVS3]
4404+\&. \(rs}
4405+\&. el .sp \(rs\(rs*[XNVS1]
4406+\&. \(rs}
4407+\&.
4408+\&. \(rs" Record <outline-level> of this entry, to compare with next
4409+\&. \(rs"
4410+\&. ie \(rs\(rs$1 .nr tc*hl \(rs\(rs$1
4411+\&. el .nr tc*hl 1
4412+\&.
4413+\&. \(rs" Set indentation, and insert <section-number> for this entry
4414+\&. \(rs"
4415+\&. nop \(rsh\(aq\(rs\(rsn[tc*hl]-1m\(aq\(rs\(rs$2\(rsc
4416+\&.
4417+\&. \(rs" Append <heading-text> for this entry
4418+\&. \(rs"
4419+\&. shift 2
4420+\&. nop \(rsh\(aq1.5n\(aq\(rs\(rs$*\(rsh\(aq0.5n\(aq
4421+\&. XE
4422+\&..
4423+.DE
4424+Used in conjunction with
4425+.CW NH
4426+and
4427+.CW XN ,
4428+this uses document\(hylocal register
4429+.CW \%tc*hl
4430+to track,
4431+group,
4432+and indent the table of contents entries for this document,
4433+on the basis of their specified
4434+.CWI outline\-level > \%<
4435+specifications,
4436+separating
4437+.CWI outline\-level > \%<
4438+groups by additional line spacing,
4439+(having an effect similar to that of increased leading),
4440+as controlled by the
4441+.CW XNVS1 ,
4442+.CW XNVS2 ,
4443+and
4444+.CW XNVS3
4445+document\(hylocal strings,
4446+at each change in
4447+.CWI outline\-level > \%< .
4448+.
4449+.NH 4
4450+.XN -S -- The \F[C]XH\-REPLACEMENT\F[] and \F[C]XN\-REPLACEMENT\F[] Macros
4451+.LP
4452+The default
4453+.CW XH
4454+and
4455+.CW XN
4456+macro implementations
4457+.EM reserve
4458+this pair of macro names,
4459+to facilitate
4460+.EM redefinition
4461+of
4462+.CW XH
4463+and
4464+.CW XN
4465+behaviour respectively,
4466+while retaining the ability to take advantage
4467+of first\(hytime\(hyof\(hyuse infrastructure initialization logic,
4468+which is incorporated within the respective default implementations.
4469+.LP
4470+It is important to understand that,
4471+in conventional usage,
4472+neither of these macros should ever be called directly.
4473+Rather,
4474+either one,
4475+or both,
4476+should be defined,
4477+.EM after
4478+loading
4479+.CW s.tmac ,
4480+and
4481+.EM before
4482+calling either
4483+.CW XH ,
4484+or
4485+.CW XN
4486+for the first time;
4487+the defined implementations are then invoked when
4488+.CW XH ,
4489+or
4490+.CW XN
4491+are called,
4492+respectively.
4493+.
4494+.LP
4495+User\(hywritten
4496+.CW \%XH\-REPLACEMENT
4497+and
4498+.CW \%XN\-REPLACEMENT
4499+macros may implement
4500+.EM any
4501+desired functionality.
4502+They are not constrained to emulation of the default
4503+.CW XH
4504+and
4505+.CW XN
4506+capabilities;
4507+however,
4508+it is
4509+.EM strongly
4510+recommended that they do so,
4511+while adding any required extended features.
4512+For example,
4513+.CW spdf.tmac
4514+defines both replacement macros thus:\**
4515+.FS
4516+An important consideration,
4517+in the design of such replacement macros,
4518+is that they will ultimately be invoked as
4519+.CW XH ,
4520+and
4521+.CW XN
4522+respectively;
4523+thus,
4524+they
4525+.EM must
4526+interpret their arguments
4527+.EM exactly
4528+as they would be passed to
4529+.CW XH
4530+and
4531+.CW XN ,
4532+and within the macro bodies,
4533+.CW \%\(rs\(rs$0
4534+will be interpreted as
4535+.CW XH
4536+or
4537+.CW XN ,
4538+as appropriate.
4539+.FE
4540+.DS I
4541+.CW
4542+\&.de XH\-REPLACEMENT als
4543+\&.als XN\-REPLACEMENT XH-REPLACEMENT
4544+\&.am XH-REPLACEMENT
4545+\&. \(rs\(rs$0\-INIT
4546+\&. rm spdf:refname
4547+\&. als spdf:bm.define spdf:bm.basic
4548+\&. while d spdf:XH\(rs\(rs$1 \(rs{\(rs
4549+\&. spdf:XH\(rs\(rs$1 \(rs\(rs$*
4550+\&. shift \(rs\(rsn[spdf:argc]
4551+\&. \(rs}
4552+\&. rr spdf:argc
4553+\&. if \(aq\(rs\(rs$1\(aq\-\-\(aq .shift
4554+\&. spdf:\(rs\(rs$0.format \(rs\(rs$@
4555+\&..
4556+.DE
4557+with macros
4558+.CW \%XH\-N ,
4559+.CW \%XH\-S ,
4560+and
4561+.CW \%XH\-X
4562+defined locally,
4563+extending the default behaviour,
4564+such that the non\(hydefault
4565+.CW \-N ,
4566+.CW \-S ,
4567+and
4568+.CW \-X
4569+option flags are interpreted,
4570+(and register
4571+.CW \%spdf:argc
4572+is set,
4573+to control the
4574+.CW while
4575+loop which does so);
4576+it further extends the default behaviour,
4577+by using locally defined macros,
4578+.CW \%spdf:XH.format ,
4579+and
4580+.CW \%spdf:XN.format ,
4581+(dynamically modified by
4582+.CW \%spdf:bm.basic ,
4583+.CW \%spdf:bm.define ,
4584+and
4585+.CW \%spdf:refname ),
4586+to propagate the specified section heading text
4587+to the PDF document outline,
4588+in addition to reproducing the default
4589+propagation to the document's table of contents,
4590+by calling
4591+.CW \%XH\-UPDATE\-TOC .
4592+.
40604593 .bp
4061-.
40624594 .NH 1
40634595 .XN -N pdf-publishing -- The PDF Publishing Process
40644596 .
diff -r 651fc10b18c4 -r aae8df304ce0 tmac/spdf.tmac
--- a/tmac/spdf.tmac Sun Feb 27 14:19:43 2022 +0000
+++ b/tmac/spdf.tmac Tue Mar 01 15:15:26 2022 +0000
@@ -91,7 +91,7 @@
9191 .\" .XH [-N <name>] [-S] [-X] <outline-level> <heading-text> ...
9292 .\" .XN [-N <name>] [-S] [-X] <heading-text> ...
9393 .\"
94-.\" Use after SH, and XN <n> respectively, to define text to be set
94+.\" Use after SH, and NH <n> respectively, to define text to be set
9595 .\" within the section heading, as a PDF document ouline entry, and
9696 .\" optionally, as a table of contents entry.
9797 .\"