doctools_plugin_apiref man page on MacOSX

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
MacOSX logo
[printable version]

doctools_plugin_apiref(n)     Documentation tools    doctools_plugin_apiref(n)

______________________________________________________________________________

NAME
       doctools_plugin_apiref - doctools plugin API reference

SYNOPSIS
       dt_copyright

       dt_file

       dt_mainfile

       dt_fileid

       dt_fmap symfname

       dt_format

       dt_imgdata key extensions

       dt_imgdst key extensions

       dt_imgsrc key extensions

       dt_lnesting

       dt_module

       dt_read file

       dt_source file

       dt_user

       ex_cappend text

       ex_cget varname

       ex_cis cname

       ex_cname

       ex_cpop cname

       ex_cpush cname

       ex_cset varname value

       ex_lb ?newbracket?

       ex_rb ?newbracket?

       fmt_initialize

       fmt_listvariables

       fmt_numpasses

       fmt_postprocess text

       fmt_setup n

       fmt_shutdown

       fmt_varset varname text

       fmt_plain_text text

_________________________________________________________________

DESCRIPTION
       This  document  is intended for plugin writers, i.e. developers wishing
       to write a doctools formatting engine for some output format X.

       It specifies the interaction between the doctools package and its plug‐
       ins,  i.e.  the	interface any doctools formatting engine has to comply
       with.

       This document deals with version 1 of the interface.

       A reader who is on the other hand more interested in  the  markup  lan‐
       guage  itself  should start with the doctools language introduction and
       proceed from there to the formal specifications, i.e. the doctools lan‐
       guage syntax and the doctools language command reference.

OVERVIEW
       The  API	 for  a	 doctools formatting engine consists of two major sec‐
       tions.

       On the one side we have a set of commands through which the  plugin  is
       able to query the frontend. These commands are provided by the frontend
       and linked into the plugin interpreter.	Please	see  section  FRONTEND
       COMMANDS for their detailed specification.

       And on the other side the plugin has to provide its own set of commands
       which will then be called by the frontend in a specific sequence	 while
       processing input. They, again, fall into two categories, management and
       formatting.  Please see section PLUGIN COMMANDS and its subsections for
       their detailed specification.

FRONTEND COMMANDS
       This section specifies the set of commands through which a plugin, also
       known as a doctools formatting engine, is able to query	the  frontend.
       These  commands are provided by the frontend and linked into the plugin
       interpreter.

       I.e. a doctools formatting engine can assume that all of the  following
       commands are present when any of its own commands (as specified in sec‐
       tion PLUGIN COMMANDS) are executed.

       Beyond that it can also assume that it has full access to its own  safe
       interpreter  and thus is not able to damage the other parts of the pro‐
       cessor, nor can it damage the filesystem.  It is however able to either
       kill  or	 hang  the  whole  process, by exiting, or running an infinite
       loop.

       Coming back to the imported commands, all the commands with prefix  dt_
       provide	limited	 access to specific parts of the frontend, whereas the
       commands with prefix ex_ provide access to  the	state  of  the	textu‐
       til::expander  object  which  does the main parsing of the input within
       the frontend. These commands should not be except  under	 very  special
       circumstances.

       dt_copyright
	      Query  command.  It  returns  a  string containing the copyright
	      information the doctools processor was configured with. The rel‐
	      evant option is -copyright).

       dt_file
	      Query  command.  It returns the full path of the file containing
	      the input currently processed by the  engine.  This  may	be  an
	      included file.

       dt_mainfile
	      Query  command.  It  returns  the full path of the toplevel file
	      containing the input currently processed by the engine.

       dt_fileid
	      Query command. It returns the name of the	 file  containing  the
	      input  currently	processed  by  the  engine,  without path, nor
	      extension.

       dt_fmap symfname
	      Query command. It returns the actual pathname to use in the out‐
	      put  in  place of the symbolic filename symfname. It will return
	      the unchanged input if no mapping was established for symfname.

	      The required mappings are established with the method map	 of  a
	      frontend, as explained in section OBJECT METHODS of the documen‐
	      tation for the package doctools.

       dt_format
	      Query command. It returns the name of the format associated with
	      the doctools formatting engine.

       dt_imgdata key extensions
	      Query  command.  Access  to  the	image  map. Looks for an image
	      recorded under the key and having on the specified extension. If
	      a	 matching image is found its data is returned as the result of
	      the command. Otherwise an empty string is returned.

       dt_imgdst key extensions
	      Query command. Access to the  image  map.	 Looks	for  an	 image
	      recorded under the key and having on the specified extension. If
	      a matching image is found its destination path in the output  is
	      returned as the result of the command. Otherwise an empty string
	      is returned.

       dt_imgsrc key extensions
	      Query command. Access to the  image  map.	 Looks	for  an	 image
	      recorded under the key and having on the specified extension. If
	      a matching image is found its origin path	 is  returned  as  the
	      result of the command. Otherwise an empty string is returned.

       dt_lnesting
	      Query command. It returns the number of lists currently open.

       dt_module
	      Query  command. It returns the name of the module the input cur‐
	      rently processed belongs to.

       dt_read file
	      Controlled filesystem access. Returns contents of file for what‐
	      ever  use desired by the plugin.	Only files which are either in
	      the same directory as the file containing the engine,  or	 below
	      it,  can be loaded. Trying to load a file outside of this direc‐
	      tory causes an error.

       dt_source file
	      Controlled filesystem access. This command allows	 the  doctools
	      formatting engine to load additional Tcl code it may need.  Only
	      files which are either in the same directory as  the  file  con‐
	      taining the engine, or below it, can be loaded. Trying to load a
	      file outside of this directory causes an error.

       dt_user
	      Query command. It returns the name of the current user as	 known
	      to  the  tcl interpreter the frontend controlling the formatting
	      engine resides in.

       ex_cappend text
	      Appends a string to the output in	 the  current  context.	  This
	      command should rarely be used by macros or application code.

       ex_cget varname
	      Retrieves	 the value of variable varname, defined in the current
	      context.

       ex_cis cname
	      Determines whether or not the name of  the  current  context  is
	      cname.

       ex_cname
	      Returns the name of the current context.

       ex_cpop cname
	      Pops a context from the context stack, returning all accumulated
	      output in that context.  The context must be named cname, or  an
	      error results.

       ex_cpush cname
	      Pushes  a	 context named cname onto the context stack.  The con‐
	      text must be popped by cpop before expansion ends	 or  an	 error
	      results.

       ex_cset varname value
	      Sets variable varname to value in the current context.

       ex_lb ?newbracket?
	      Returns  the  current value of the left macro expansion bracket;
	      this is for use as or within a macro, when the bracket needs  to
	      be  included in the output text.	If newbracket is specified, it
	      becomes the new bracket, and is returned.

       ex_rb ?newbracket?
	      Returns the current value of the right macro expansion  bracket;
	      this  is for use as or within a macro, when the bracket needs to
	      be included in the output text.  If newbracket is specified,  it
	      becomes the new bracket, and is returned.

PLUGIN COMMANDS
       The  plugin  has	 to provide its own set of commands which will then be
       called by the frontend in a specific sequence while  processing	input.
       They  fall  into	 two  categories,  management  and  formatting.	 Their
       expected names, signatures, and responsibilities are specified  in  the
       following two subsections.

   MANAGEMENT COMMANDS
       The  management	commands a plugin has to provide are used by the fron‐
       tend to

       [1]    initialize and shutdown the plugin

       [2]    determine the number of passes it has to make over the input

       [3]    initialize and shutdown each pass

       [4]    query and initialize engine parameters

       After the plugin has been loaded and the frontend commands  are	estab‐
       lished the commands will be called in the following sequence:

	   fmt_numpasses -> n
	   fmt_listvariables -> vars

	   fmt_varset var1 value1
	   fmt_varset var2 value2
	   ...
	   fmt_varset varK valueK
	   fmt_initialize
	   fmt_setup 1
	   ...
	   fmt_setup 2
	   ...
	   ...
	   fmt_setup n
	   ...
	   fmt_postprocess
	   fmt_shutdown
	   ...

       I.e. first the number of passes and the set of available engine parame‐
       ters is established, followed by calls  setting	the  parameters.  That
       second part is optional.

       After  that  the	 plugin is initialized, the specified number of passes
       executed, the final result run through a global	post  processing  step
       and  at last the plugin is shutdown again. This can be followed by more
       conversions, restarting the sequence at fmt_varset.

       In each of the passes, i.e. after the calls of fmt_setup	 the  frontend
       will  process  the  input and call the formatting commands as markup is
       encountered. This means that the sequence  of  formatting  commands  is
       determined by the grammar of the doctools markup language, as specified
       in the doctools language syntax specification.

       A different way of looking at the sequence is:

       ·      First some basic parameters are determined.

       ·      Then everything starting at the first fmt_varset to fmt_shutdown
	      forms  a	run, the formatting of a single input. Each run can be
	      followed by more.

       ·      Embedded within each run we have one or more passes, each start‐
	      ing  with fmt_setup and going until either the next fmt_setup or
	      fmt_postprocess is reached.

	      If more than one pass is required to perform the formatting only
	      the  output  of the last pass is relevant. The output of all the
	      previous, preparatory passes is ignored.

       The commands, their names, signatures,  and  responsibilities  are,  in
       detail:

       fmt_initialize
	      Initialization/Shutdown.	 This  command is called at the begin‐
	      ning of every conversion run, as the first command of that  run.
	      Note  that  a  run  is  not  a pass, but may consist of multiple
	      passes.  It has to initialize the general state of  the  plugin,
	      beyond  the initialization done during the load. No return value
	      is expected, and any returned value is ignored.

       fmt_listvariables
	      Initialization/Shutdown and Engine parameters.   Second  command
	      is  called  after	 the plugin code has been loaded, i.e. immedi‐
	      ately after fmt_numpasses.  It has to return a  list  containing
	      the  names  of  the parameters the frontend can set to configure
	      the engine. This list can be empty.

       fmt_numpasses
	      Initialization/Shutdown  and  Pass  management.	First  command
	      called  after  the plugin code has been loaded. No other command
	      of the engine will be called before it.  It has  to  return  the
	      number of passes this engine requires to fully process the input
	      document. This value has to be  an  integer  number  greater  or
	      equal to one.

       fmt_postprocess text
	      Initialization/Shutdown.	 This  command	is  called immediately
	      after the last pass in a run. Its argument is the result of  the
	      conversion  generated  by that pass. It is provided to allow the
	      engine to perform any global modifications of the generated doc‐
	      ument.  If  no post-processing is required for a specific format
	      the command has to just return the argument.

	      Expected to return a value, the final result of  formatting  the
	      input.

       fmt_setup n
	      Initialization/Shutdown  and  Pass  management.  This command is
	      called at the beginning of each pass over the input  in  a  run.
	      Its  argument  is the number of the pass which has begun. Passes
	      are counted from 1 upward.  The command has to set up the inter‐
	      nal  state  of  the  plugin  for this particular pass. No return
	      value is expected, and any returned value is ignored.

       fmt_shutdown
	      Initialization/Shutdown.	This command is called at the  end  of
	      every conversion run. It is the last command called in a run. It
	      has to clean up of all the run-specific  state  in  the  plugin.
	      After  the call the engine has to be in a state which allows the
	      initiation of another run without fear that information from the
	      last  run	 is  leaked  into  this	 new  run.  No return value is
	      expected, and any returned value is ignored.

       fmt_varset varname text
	      Engine parameters.  This command is called by  the  frontend  to
	      set an engine parameter to a particular value.  The parameter to
	      change is specified by varname, the value to set in text.

	      The command has to throw an error if an unknown varname is used.
	      Only  the names returned by fmt_listvariables have to be consid‐
	      ered as known.

	      The values of all engine	parameters  have  to  persist  between
	      passes and runs.

   FORMATTING COMMANDS
       The formatting commands have to implement the formatting for the output
       format, for all the markup commands of the  doctools  markup  language,
       except  lb,  rb,	 vset, include, and comment. These exceptions are pro‐
       cessed by the frontend and are never seen by the plugin.	 In  return  a
       command	for the formatting of plain text has to be provided, something
       which has no markup in the input at all.

       This means, that each of the 49 markup commands specified in  the  doc‐
       tools  language	command reference and outside of the set of exceptions
       listed above has an equivalent formatting command which takes the  same
       arguments  as  the  markup command and whose name is the name of markup
       command with the prefix fmt_ added to it.

       All commands are expected to format their input in  some	 way  per  the
       semantics  specified  in	 the  command reference and to return whatever
       part of this that they deem necessary as their result,  which  will  be
       added to the output.

       To  avoid  essentially duplicating the command reference we do not list
       any of the command here and simply refer the  reader  to	 the  doctools
       language	 command  reference  for  their signature and description. The
       sole exception is the plain text formatter,  which  has	no  equivalent
       markup command.

       The  calling sequence of formatting commands is not as rigid as for the
       management commands, but determined by  the  grammar  of	 the  doctools
       markup  language, as specified in the doctools language syntax specifi‐
       cation.

       fmt_plain_text text
	      No associated markup command.

	      Called by the frontend for any plain  text  encountered  in  the
	      input. It has to perform any and all special processing required
	      for plain text.

	      The formatted text is expected as the result of the command, and
	      added to the output. If no special processing is required it has
	      to simply return its argument without change.

BUGS, IDEAS, FEEDBACK
       This document,  will  undoubtedly  contain  bugs	 and  other  problems.
       Please  report  such in the category doctools of the Tcllib SF Trackers
       [http://sourceforge.net/tracker/?group_id=12883].  Please  also	report
       any ideas for enhancements you may have.

SEE ALSO
       doctools, doctools_intro, doctools_lang_cmdref, doctools_lang_faq, doc‐
       tools_lang_intro, doctools_lang_syntax

KEYWORDS
       document,  formatter,  formatting  engine,  manpage,  markup,  semantic
       markup

CATEGORY
       Documentation tools

COPYRIGHT
       Copyright (c) 2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>

doctools			      1.1	     doctools_plugin_apiref(n)
[top]

List of man pages available for MacOSX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net