summaryrefslogtreecommitdiff
path: root/web/tango-weevil/weevinfo.tw
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /web/tango-weevil/weevinfo.tw
Initial commit
Diffstat (limited to 'web/tango-weevil/weevinfo.tw')
-rw-r--r--web/tango-weevil/weevinfo.tw418
1 files changed, 418 insertions, 0 deletions
diff --git a/web/tango-weevil/weevinfo.tw b/web/tango-weevil/weevinfo.tw
new file mode 100644
index 0000000000..7f800b4a95
--- /dev/null
+++ b/web/tango-weevil/weevinfo.tw
@@ -0,0 +1,418 @@
+%
+% Tango/Weevil - A WEB Tangler and Weaver
+% Copyright (C) 1995 Corey Minyard
+%
+% This program is free software; you can redistribute it and/or modify
+% it under the terms of the GNU General Public License as published by
+% the Free Software Foundation; either version 2 of the License, or
+% (at your option) any later version.
+%
+% This program is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of
+% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+% GNU General Public License for more details.
+%
+% You should have received a copy of the GNU General Public License
+% along with this program; if not, write to the Free Software
+% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+%
+% Corey Minyard - minyard@metronet.com
+%
+\section{Weevil Information Include Introduction}
+
+This file contains the information used by weevil and the language and
+output handlers that interface to weevil.
+
+@code <*>
+#ifdef __cplusplus__
+extern "C"
+{
+#endif
+
+@<Defines>
+@<Structures>
+@<C Language Routines>
+@<LaTeX Routines>
+
+#ifdef __cplusplus__
+}
+#endif
+@endcode
+
+\section{Interfacing Languages to Weevil}
+
+A language definition requires two simple procedure calls. A
+character handler handles all code a character at a time. It's job is
+to tell weevil how to handle the character. It is passed the standard
+weevil data, a character, and the next character in the sequence. It
+returns the following codes:
+
+\begin{description}
+\item[PROCESS\_CHAR\_NORMALLY] This is a standard character that
+should be handled normally by weevil.
+\item[PROCESS\_CHAR\_INSTRING] This character is in a string or
+comment, it should not be scanned for special weevil characters.
+\item[PROCESS\_CHAR\_SKIPNEXT] This character and the following
+character should be skipped without being scanned for special weevil
+characters.
+\end{description}
+
+The other procedure is an initialization handler, which may initialize
+the language handler.
+
+\section{Interfacing Output Types to Weevil}
+
+An output type requires a lot of function calls but is conceptually
+simple. Each function call output a certain portion of the output,
+just provide the proper output mechanism, add all the functions to the
+list of output modes, and it's done. Section~\ref{weevinfo-defines}
+has the typedefs and descriptions for all the functions.
+
+\begin{sloppypar}
+Weevil has a number of output modes. Documentation modes is the mode
+weevil starts in, it will just output everything as-is until it finds
+a code chunk (marked by \verb|@code|). Then it switches to code mode
+after calling \verb|begin_macro_handler|. Code mode calls the
+language character handler on each character to find out if it is in a
+string, comment, etc. It will output characters normally until it
+sees an \verb|@| (unless in a string or comment). If it sees an
+\verb|@@|, it will output a single \verb|@|. If it sees a
+\verb|@<name>|, it will call \verb|output_macro_use_handler| with the
+name. It will \emph{not} output the \verb|@<name>|. At the end of
+the code chunk, \verb|end_macro_handler| will be called. At the
+beginning of each line, \verb|output_linenum_handler| will be called.
+\end{sloppypar}
+
+After a code chunk has been output, if cross references for any
+variable uses exist for the code chunk then uses mode will be entered,
+where each variable used by the code chunk will be output. A begin
+handler is called, then for each cross reference the name handle is
+called and a handler is called for each place where the name is
+declared is given. Then an end name handler is called. After all
+uses have been output, an end handler is called.
+
+If declaration cross references exist, they are output next. A begin
+handler is called, then a handler for each variable name, then an end
+handler for the declaration list.
+
+If any cross references were output, a handler is called after all
+cross references have been output. Then documentation mode is entered
+again.
+
+\section{Defines}
+\label{weevinfo-defines}
+The following code chunk has miscellaneous definitions and the
+typedefs for all the language-specific and output-specific procedures
+used by weevil. Each procedure is also described in detail in the
+comment before it.
+
+@code <Defines>
+#define MAXLINESIZE 200
+
+#define TRUE 1
+#define FALSE 0
+typedef int bool;
+
+
+/* Is the processor processing stuff between @code and @endcode or
+ is is processing documentation? Used by the codestate
+ variable. */
+#define IN_CODE 1
+#define NOT_IN_CODE 2
+
+
+#define PROCESS_CHAR_NORMALLY 0
+#define PROCESS_CHAR_INSTRING 1
+#define PROCESS_CHAR_SKIPNEXT 2
+
+struct s_lpweevildat;
+
+/****************************************************************
+**
+** These are for languages.
+**
+****************************************************************/
+
+/*
+ * Process the code a character at a time. The current and next
+ * character are provided. Return PROCESS_CHAR_NORMALLY for
+ * standard output, PROCESS_CHAR_INSTRING if in a string or
+ * comment, or PROCESS_CHAR_SKIPNEXT if the current and next
+ * character should not be processed (just output).
+ */
+typedef int (*char_handler)(struct s_lpweevildat *lpwd,
+ char c,
+ char next_c);
+
+/*
+ * Initialize the language handler. This may use the
+ * language-specific pointer in lpwd to store info for
+ * itself.
+ */
+typedef void (*handler_init)(struct s_lpweevildat *lpwd);
+
+
+/****************************************************************
+**
+** These are for documentation output.
+**
+****************************************************************/
+
+/*
+ * Initialize the mode handler. This may use the mode-specific
+ * pointer in lpwd to store info for itself.
+ */
+typedef void (*mode_init)(struct s_lpweevildat *lpwd);
+
+/*
+ * Handle the beginning of a code chunk. The name of the code
+ * chunk is passed in.
+ */
+typedef void (*begin_macro_handler)(struct s_lpweevildat *lpwd,
+ char *name);
+
+/*
+ * Handle the end of a code chunk.
+ */
+typedef void (*end_macro_handler)(struct s_lpweevildat *lpwd);
+
+/*
+ * Handle the end after all cross references and everything.
+ */
+typedef void (*finalend_chunk_handler)(struct s_lpweevildat *lpwd);
+
+/*
+ * Output the use of a code chunk in some code. The name of
+ * the code chunk is given.
+ */
+typedef void
+(*output_macro_use_handler)(struct s_lpweevildat *lpwd,
+ char *macro_name);
+
+/*
+ * Output the line number at the beginning of the code chunk.
+ */
+typedef void
+(*output_linenum_handler)(struct s_lpweevildat *lpwd);
+
+/*
+ * Output a single normal character.
+ */
+typedef void
+(*output_char_handler)(struct s_lpweevildat *lpwd,
+ char c);
+
+/*
+ * Handle the beginning of a list of uses cross-references.
+ */
+typedef void
+(*output_begin_uses_handler)(struct s_lpweevildat *lpwd);
+
+/*
+ * Handle the end of a list of uses cross-references.
+ */
+typedef void
+(*output_end_uses_handler)(struct s_lpweevildat *lpwd);
+
+/*
+ * Handle the start of a single use cross reference. The name of
+ * the variable is given.
+ */
+typedef void
+(*output_use_start_handler)(struct s_lpweevildat *lpwd,
+ char *name);
+
+/*
+ * Handle the end of a single use cross reference. The name of
+ * the variable is given.
+ */
+typedef void
+(*output_use_end_handler)(struct s_lpweevildat *lpwd,
+ char *name);
+
+/*
+ * Output a use cross reference location. The file and macro
+ * of the declaration is given. The name being cross-referenced
+ * is also given.
+ */
+typedef void
+(*output_use_ref_handler)(struct s_lpweevildat *lpwd,
+ char *file,
+ char *macro,
+ char *name);
+
+/*
+ * Handle between each use of a cross reference.
+ */
+typedef void
+(*output_between_use_refs_handler)(struct s_lpweevildat *lpwd,
+ char *name);
+
+/*
+ * Handle the beginning of a list of declares cross-references.
+ */
+typedef void
+(*output_begin_decls_handler)(struct s_lpweevildat *lpwd);
+
+/*
+ * Handle the end of a list of declares cross-references.
+ */
+typedef void
+(*output_end_decls_handler)(struct s_lpweevildat *lpwd);
+
+/*
+ * Handle the output of a single declaration.
+ */
+typedef void
+(*output_decl_handler)(struct s_lpweevildat *lpwd,
+ char *name);
+
+/*
+ * Handle the end of cross references. This is only called if
+ * cross-references were created.
+ */
+typedef void
+(*output_after_xrefs_handler)(struct s_lpweevildat *lpwd);
+@endcode
+
+\section{Structures}
+Various structures used by weevil are put here.
+
+@code <Structures>
+@<xreflist>
+@<lpweevildat>
+@endcode
+
+\subsection{xreflist}
+This list contains list of cross references and information on where
+they are declared.
+
+@code <xreflist>
+typedef struct s_xreflist
+{
+ struct s_xreflist *next;
+ char *file;
+ char *macro;
+ char *name;
+} xreflist;
+@endcode
+
+\subsection{lpweevildat}
+This large structure contains everything there is to know about what
+weevil is doing.
+
+@code <lpweevildat>
+typedef struct s_lpweevildat
+{
+ FILE *infile; /* File to get input from. */
+ FILE *outfile; /* File to send output. */
+ char line[MAXLINESIZE]; /* Current input line. */
+
+ int codestate; /* Current output state. */
+ char *curr_filename; /* Name of the input file being
+ processed. */
+ char *curr_macro; /* Current macro being input. */
+ int maxlinesize; /* Maximum size of an input line. */
+ int curr_lineno; /* Current input line number. */
+ int code_lineno; /* Current code output line number. */
+
+ int retcode; /* Program return code. */
+
+ void *lang_data; /* Data for language mode. */
+ void *mode_data; /* Data for output mode. */
+
+ xreflist *pounddefs; /* List of #defines. */
+ xreflist *vardefs; /* List of variable defines. */
+ xreflist *uses; /* List of variable uses. */
+
+ xreflist *includes; /* List of places to look for
+ .xfr files. */
+
+ /* Routine to scan code in a language-specific way. */
+ char_handler handle_char;
+
+ /* Routines to output data for the output mode. */
+ begin_macro_handler begin_macro;
+ end_macro_handler end_macro;
+ finalend_chunk_handler finalend_chunk;
+ output_macro_use_handler output_macro_use;
+ output_linenum_handler output_linenum;
+ output_char_handler output_char;
+ output_begin_uses_handler output_begin_uses;
+ output_end_uses_handler output_end_uses;
+ output_use_start_handler output_use_start;
+ output_use_end_handler output_use_end;
+ output_use_ref_handler output_use_ref;
+ output_between_use_refs_handler output_between_use_refs;
+ output_begin_decls_handler output_begin_decls;
+ output_end_decls_handler output_end_decls;
+ output_decl_handler output_decl;
+ output_after_xrefs_handler output_after_xrefs;
+} t_lpweevildat;
+@endcode
+
+\section{Language Dependent Routines}
+Here are forward-declared all the routines for the various languages
+handled by weevil.
+
+\subsection{C}
+
+@code <C Language Routines>
+int c_handle_char(t_lpweevildat *lpwd,
+ char c,
+ char next_c);
+
+void init_c_lang(t_lpweevildat *lpwd);
+@endcode
+
+\section{Output Mode Routines}
+Here are forward-declared all the routines for the various output modes
+handled by weevil.
+
+\subsection{\LaTeX}
+
+@code <LaTeX Routines>
+void latex_mode_init(t_lpweevildat *lpwd);
+
+void latex_begin_macro(t_lpweevildat *lpwd,
+ char *name);
+
+void latex_end_macro(t_lpweevildat *lpwd);
+
+void latex_finalend_chunk(t_lpweevildat *lpwd);
+
+void latex_output_macro_use(t_lpweevildat *lpwd,
+ char *macro_name);
+
+void latex_output_linenum(t_lpweevildat *lpwd);
+
+void latex_output_char(t_lpweevildat *lpwd,
+ char c);
+
+void latex_output_begin_uses(t_lpweevildat *lpwd);
+
+void latex_output_end_uses(t_lpweevildat *lpwd);
+
+void latex_output_use_start(t_lpweevildat *lpwd,
+ char *name);
+
+void latex_output_use_end(t_lpweevildat *lpwd,
+ char *name);
+
+void latex_output_use_ref(t_lpweevildat *lpwd,
+ char *file,
+ char *macro,
+ char *name);
+
+void latex_output_between_use_refs(t_lpweevildat *lpwd,
+ char *name);
+
+void latex_output_begin_decls(t_lpweevildat *lpwd);
+
+void latex_output_end_decls(t_lpweevildat *lpwd);
+
+void latex_output_decl(t_lpweevildat *lpwd,
+ char *name);
+
+void latex_output_after_xrefs(t_lpweevildat *lpwd);
+@endcode