[Groff] Implement the groff_mdoc(7) .%C (city) macro

[Ingo Schwarze]

Hi,

in the CVS HEAD version of groff, the manual groff_mdoc(7) still says:

  .It Li .%C
  City/place (not implemented yet).

And indeed, the file tmac/doc.tmac does not implement the .%C city
submacro of .Rs citation blocks.

Are there particular reasons why the groff mdoc macros do not support
the .%C macro?  Otherwise, i'd like to propose the following
implementation.  I think .%C is useful because most citation data
includes information about the publishing location, so i think there
is ample opportunity to use this in practice.

Note that my implementation is not very original, but mostly
copy-and-paste style of existing code found elsewhere in the
file doc.tmac.  But given that the other .%-Macros all use copies
of very similar code, that's probably the best option in the current
framework.

Given that i mostly copied and pasted, i don't think this patch
causes new Copyright to emerge, so we aren't going to need a formal
Copyright reassignment.

What do you think?
  Ingo


Index: ChangeLog
===================================================================
RCS file: /sources/groff/groff/ChangeLog,v
retrieving revision 1.1432
diff -u -p -r1.1432 ChangeLog
--- ChangeLog   16 Jul 2013 14:32:02 -0000      1.1432
+++ ChangeLog   25 Jul 2013 09:44:32 -0000
@@ -1,3 +1,7 @@
+2013-07-24  Ingo Schwarze <address@hidden>
+
+       * tmac/doc.tmac, tmac/doc-common, tmac/groff_mdoc.man: Implement .%C.
+
 2013-07-16  Werner LEMBERG  <address@hidden>
 
        * tmac/fallbacks.tmac: Make it work in compatibility mode.
Index: tmac/doc-common
===================================================================
RCS file: /sources/groff/groff/tmac/doc-common,v
retrieving revision 1.46
diff -u -p -r1.46 doc-common
--- tmac/doc-common     29 Oct 2011 16:44:31 -0000      1.46
+++ tmac/doc-common     25 Jul 2013 09:44:37 -0000
@@ -37,6 +37,7 @@
 .
 .nr %A 1
 .nr %B 1
+.nr %C 1
 .nr %D 1
 .nr %I 1
 .nr %J 1
Index: tmac/doc.tmac
===================================================================
RCS file: /sources/groff/groff/tmac/doc.tmac,v
retrieving revision 1.44
diff -u -p -r1.44 doc.tmac
--- tmac/doc.tmac       18 Jul 2012 08:50:52 -0000      1.44
+++ tmac/doc.tmac       25 Jul 2013 09:44:46 -0000
@@ -3423,6 +3423,8 @@
 .
 .  nr doc-book-count-saved \n[doc-book-count]
 .  ds doc-book-name-saved "\*[doc-book-name]
+.  nr doc-city-count-saved \n[doc-city-count]
+.  ds doc-city-name-saved "\*[doc-city-name]
 .  nr doc-date-count-saved \n[doc-date-count]
 .  ds doc-date-saved "\*[doc-date]
 .  nr doc-publisher-count-saved \n[doc-publisher-count]
@@ -3565,6 +3567,8 @@
 .
 .  nr doc-book-count \n[doc-book-count-saved]
 .  ds doc-book-name "\*[doc-book-name-saved]
+.  nr doc-city-count \n[doc-city-count-saved]
+.  ds doc-city-name "\*[doc-city-name-saved]
 .  nr doc-date-count \n[doc-date-count-saved]
 .  ds doc-date "\*[doc-date-saved]
 .  nr doc-publisher-count \n[doc-publisher-count-saved]
@@ -5190,6 +5194,8 @@
 .\" NS   doc-author-nameXXX
 .\" NS   doc-book-count
 .\" NS   doc-book-name
+.\" NS   doc-city-count
+.\" NS   doc-city-name
 .\" NS   doc-corporate-count
 .\" NS   doc-corporate-name
 .\" NS   doc-date
@@ -5228,6 +5234,7 @@
 .  nr doc-reference-title-count 0
 .  nr doc-url-count 0
 .  nr doc-volume-count 0
+.  nr doc-city-count 0
 .  nr doc-date-count 0
 .  nr doc-page-number-count 0
 .  nr doc-book-count 0
@@ -5243,6 +5250,7 @@
 .  ds doc-reference-title-name-for-book
 .  ds doc-url-name
 .  ds doc-volume-name
+.  ds doc-city-name
 .  ds doc-date
 .  ds doc-page-number-string
 .  ds doc-book-name
@@ -5357,6 +5365,13 @@
 .    doc-finish-reference \n[doc-corporate-count]
 .  \}
 .
+.  if \n[doc-city-count] \{\
+.    unformat doc-city-name
+.    chop doc-city-name
+.    nop \*[doc-city-name]\c
+.    doc-finish-reference \n[doc-city-count]
+.  \}
+.
 .  if \n[doc-date-count] \{\
 .    unformat doc-date
 .    chop doc-date
@@ -5528,6 +5543,60 @@
 ..
 .
 .
+.\" NS doc-city-count global register
+.\" NS   counter of city references
+.
+.nr doc-city-count 0
+.
+.
+.\" NS doc-city-name global box
+.\" NS   string of collected city references
+.
+.ds doc-city-name
+.
+.
+.\" NS %C user macro
+.\" NS   [reference] city
+.\" NS
+.\" NS modifies:
+.\" NS   doc-arg-ptr
+.\" NS   doc-curr-font
+.\" NS   doc-curr-size
+.\" NS   doc-city-count
+.\" NS   doc-macro-name
+.\" NS   doc-reference-count
+.\" NS
+.\" NS local variables:
+.\" NS   doc-env-%C
+.\" NS
+.\" NS width register `%C' set in doc-common
+.
+.de %C
+.  if (\n[doc-arg-limit] : (\n[.$] == 0)) \{\
+.    tm Usage: .%C city_name ... (#\n[.c])
+.    return
+.  \}
+.
+.  nr doc-city-count +1
+.  nr doc-reference-count +1
+.
+.  ds doc-macro-name %C
+.  doc-parse-args \$@
+.
+.  nr doc-arg-ptr +1
+.  nr doc-curr-font \n[.f]
+.  nr doc-curr-size \n[.ps]
+.
+.  \" append to reference box
+.  boxa doc-city-name
+.  ev doc-env-%C
+.  evc 0
+.  in 0
+.  nf
+.  doc-do-references
+..
+.
+.
 .\" NS doc-date-count global register
 .\" NS   counter of date references
 .
Index: tmac/groff_mdoc.man
===================================================================
RCS file: /sources/groff/groff/tmac/groff_mdoc.man,v
retrieving revision 1.57
diff -u -p -r1.57 groff_mdoc.man
--- tmac/groff_mdoc.man 14 Aug 2012 21:48:03 -0000      1.57
+++ tmac/groff_mdoc.man 25 Jul 2013 09:44:52 -0000
@@ -2637,7 +2637,7 @@ Reference author name; one name per invo
 .It Li .%B
 Book title.
 .It Li .%C
-City/place (not implemented yet).
+City/place.
 .It Li .%D
 Date.
 .It Li .%I
@@ -2684,7 +2684,8 @@ Example:
 \&.%A "John Foo"
 \&.%T "Implementation Notes on foobar(1)"
 \&.%R "Technical Report ABC\-DE\-12\-345"
-\&.%Q "Drofnats College, Nowhere"
+\&.%Q "Drofnats College"
+\&.%C "Nowhere"
 \&.%D "April 1991"
 \&.Re
 .Ed
@@ -2697,7 +2698,8 @@ produces
 .%A "John Foo"
 .%T "Implementation Notes on foobar(1)"
 .%R "Technical Report ABC-DE-12-345"
-.%Q "Drofnats College, Nowhere"
+.%Q "Drofnats College"
+.%C "Nowhere"
 .%D "April 1991"
 .Re
 .Ed