[gnugo-devel] [patch] harvesting gtp commands for the manual

[Thien-Thi Nguyen]

hi gnugo folks,

i am interested in rewriting gnugo.el to use the go text protocol, but
there is currently no reference material in the otherwise excellent
manual, which got me thinking...

please find below a small patch to doc/{gtp.texi,Makefile.am} that
allows automatic harvesting of the (well-ordered and nicely regular)
comments in interface/play_gtp.c to produce a texinfo frag suitable for
@inclusion.  the Makefile.am entry references gtp-commands.sed, which i
will send in a separate mail (since it's a new file).

here is a change log entry:

2002-10-30  Thien-Thi Nguyen  <address@hidden>

        * doc/gtp-commands.sed: New file.

        * doc/Makefile.am (BUILT_SOURCES): New directive.
        (gnugo_TEXINFOS, EXTRA_DIST): Add gtp-commands.texi.
        (cmdsrc): New var.
        (gtp-commands.texi): New target.

        * doc/gtp.texi (GTP command reference): New section.
        (The Go Text Protocol): Replace interface/play_gtp.c
        reference w/ xref to new section.

now i can rewrite gnugo.el w/ some handy docs. (-;

thi


___________________________________________
cd /home/ttn/build/GNU/gnugo/doc/
cvs -f diff -c -w Makefile.am gtp.texi
Index: Makefile.am
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/Makefile.am,v
retrieving revision 1.4
diff -c -w -r1.4 Makefile.am
*** Makefile.am 19 Apr 2002 23:45:18 -0000      1.4
--- Makefile.am 30 Oct 2002 12:20:55 -0000
***************
*** 4,10 ****
  info_TEXINFOS = gnugo.texi
  
  gnugo_TEXINFOS = analyze.texi api.texi board.texi copying.texi dfa.texi \
!                  dragon.texi eyes.texi gnugo.texi gtp.texi \
                   influence.texi introduction.texi move_generation.texi \
                   moyo.texi overview.texi owl.texi patterns.texi \
                   reading.texi regression.texi sgf.texi using.texi \
--- 4,10 ----
  info_TEXINFOS = gnugo.texi
  
  gnugo_TEXINFOS = analyze.texi api.texi board.texi copying.texi dfa.texi \
!                  dragon.texi eyes.texi gnugo.texi gtp.texi gtp-commands.texi \
                   influence.texi introduction.texi move_generation.texi \
                   moyo.texi overview.texi owl.texi patterns.texi \
                   reading.texi regression.texi sgf.texi using.texi \
***************
*** 22,28 ****
  JPG = cdfa.jpg dfa.jpg dfa2.jpg oldlogo.jpg path.jpg sync-prod1.jpg \
        sync-prod2.jpg newlogo.jpg
  
! EXTRA_DIST = automake-1.4.patch gnugo.6 gnugo.pod $(EPS) $(FIG) $(PNG) $(JPG)
  
  CLEANFILES = *.log *.dvi *.aux *.vr *.tp *.ky *.pg *.cps *.fns *.toc \
               *.fn *.cp *~
--- 22,29 ----
  JPG = cdfa.jpg dfa.jpg dfa2.jpg oldlogo.jpg path.jpg sync-prod1.jpg \
        sync-prod2.jpg newlogo.jpg
  
! EXTRA_DIST = automake-1.4.patch gnugo.6 gnugo.pod gtp-commands.sed \
!       $(EPS) $(FIG) $(PNG) $(JPG)
  
  CLEANFILES = *.log *.dvi *.aux *.vr *.tp *.ky *.pg *.cps *.fns *.toc \
               *.fn *.cp *~
***************
*** 30,32 ****
--- 31,45 ----
  gnugo.6: $(srcdir)/gnugo.pod
        pod2man $(srcdir)/gnugo.pod --section 6 --release @VERSION@ > gnugo.6
  
+ BUILT_SOURCES = gtp-commands.texi
+ 
+ cmdsrc = $(srcdir)/../interface/play_gtp.c
+ 
+ gtp-commands.texi: $(cmdsrc)
+       cp $(srcdir)/gtp-commands.sed TMP.sed
+       sed -e '/static struct gtp_command commands/,/^}/!d'            \
+           -e '/^ /!d' -e '/NULL/d'                                    \
+           -e 's/ *{"\(.*\)"[^a-z]*\(gtp_[a-z_]*\)}.*/s,\2,\1,g/'      \
+           $(cmdsrc) >> TMP.sed
+       sed -f TMP.sed $(cmdsrc) > $(srcdir)/gtp-commands.texi
+       rm -f TMP.sed
Index: gtp.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/gtp.texi,v
retrieving revision 1.7
diff -c -w -r1.7 gtp.texi
*** gtp.texi    8 Aug 2002 21:35:21 -0000       1.7
--- gtp.texi    30 Oct 2002 12:20:56 -0000
***************
*** 4,9 ****
--- 4,10 ----
  * Protocol applications::         Protocol applications
  * Protocol conventions::        Protocol conventions
  * Regression with GTP::           Regression testing with GTP
+ * GTP command reference::         Details on every GTP command
  @end menu
  
  @node The Go Text Protocol, Protocol applications, GTP, GTP
***************
*** 151,158 ****
  worm_data
  @end example
  
! For exact specification of their arguments and results we refer to the
! comments of the functions in @file{interface/play_gtp.c}.
  
  @node Protocol applications, Protocol conventions, The Go Text Protocol, GTP
  @section Protocol applications
--- 152,160 ----
  worm_data
  @end example
  
! For exact specification of their arguments and results,
! @xref{GTP command reference}.
! 
  
  @node Protocol applications, Protocol conventions, The Go Text Protocol, GTP
  @section Protocol applications
***************
*** 339,345 ****
  @}
  @end example
  
! @node Regression with GTP, , Protocol conventions, GTP
  @comment  node-name,  next,  previous,  up
  @section Regression testing with GTP
  
--- 341,347 ----
  @}
  @end example
  
! @node Regression with GTP, GTP command reference, Protocol conventions, GTP
  @comment  node-name,  next,  previous,  up
  @section Regression testing with GTP
  
***************
*** 350,352 ****
--- 352,380 ----
  results are then compared with expected results encoded in GTP comments
  in the file, using matching with regular expressions. More information
  can be found in the regression chapter (@pxref{Regression}).
+ 
+ @node GTP command reference, , Regression with GTP, GTP
+ @section GTP command reference
+ 
+ This section lists the GTP command set along with some information about each
+ command.  Each entry in the list has the following fields:
+ 
+ @itemize @bullet
+ @item Function: What this command does.
+ @item Arguments: What other information, if any, this command requires.
+ Typical values include @dfn{none} or @dfn{vertex} or @dfn{integer} (there
+ are others).
+ @item Fails: Circumstances which cause this command to fail.
+ @item Returns: What is displayed after the @dfn{=} and before the two
+ newlines.  Typical values include @dfn{nothing} or @dfn{a move coordinate}
+ or some status string (there are others).
+ @item Status: How this command fits in with the GTP API.
+ @end itemize
+ 
+ For suggestions on how to make effective use of the GTP command set,
+ @xref{Protocol applications}.  Without further ado, here is the big list (in
+ no particular order):
+ 
+ @itemize @bullet
+ @include gtp-commands.texi
+ @end itemize

Compilation exited abnormally with code 1 at Wed Oct 30 04:08:12