docidx_plugin_apiref man page on Ubuntu

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

docidx_plugin_apiref(3tcl)    Documentation tools   docidx_plugin_apiref(3tcl)

______________________________________________________________________________

NAME
       docidx_plugin_apiref - docidx plugin API reference

SYNOPSIS
       dt_fmap symfname

       dt_format

       dt_read file

       dt_source file

       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?

       idx_initialize

       idx_listvariables

       idx_numpasses

       idx_postprocess text

       idx_setup n

       idx_shutdown

       idx_varset varname text

       fmt_plain_text text

_________________________________________________________________

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

       It specifies the interaction between the doctools::idx package and  its
       plugins,	 i.e.  the interface any index 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 docidx language introduction and
       proceed from there to the formal specifications, i.e. the  docidx  lan‐
       guage syntax and the docidx language command reference.

OVERVIEW
       The API for an index formatting engine consists of two major sections.

       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  an  index  formatting engine, is able to query the frontend.
       These commands are provided by the frontend and linked into the	plugin
       interpreter.

       I.e.  an	 index	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_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::idx.

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

       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 index for‐
	      matting 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.

       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:

	   idx_numpasses -> n
	   idx_listvariables -> vars

	   idx_varset var1 value1
	   idx_varset var2 value2
	   ...
	   idx_varset varK valueK
	   idx_initialize
	   idx_setup 1
	   ...
	   idx_setup 2
	   ...
	   ...
	   idx_setup n
	   ...
	   idx_postprocess
	   idx_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 idx_varset.

       In  each	 of the passes, i.e. after the calls of idx_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 docidx markup language,	 as  specified
       in the docidx language syntax specification.

       A different way of looking at the sequence is:

       ·      First some basic parameters are determined.

       ·      Then everything starting at the first idx_varset to idx_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 idx_setup and going until either the next idx_setup  or
	      idx_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:

       idx_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.

       idx_listvariables
	      Initialization/Shutdown  and  Engine parameters.	Second command
	      is called after the plugin code has been	loaded,	 i.e.  immedi‐
	      ately  after  idx_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.

       idx_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.

       idx_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.

       idx_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.

       idx_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.

       idx_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 idx_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 docidx 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 five markup commands specified in the
       docidx 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 docidx lan‐
       guage 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 docidx markup
       language, as specified in the docidx language syntax specification.

       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
       docidx_intro,  docidx_lang_cmdref,  docidx_lang_faq, docidx_lang_intro,
       docidx_lang_syntax, doctools::idx

KEYWORDS
       formatting engine, index, index formatter,  keywords,  markup,  plugin,
       semantic markup

CATEGORY
       Documentation tools

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

doctools			      1.0	    docidx_plugin_apiref(3tcl)
[top]

List of man pages available for Ubuntu

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