From: Mark Wooding Date: Sat, 27 Jul 2019 16:25:18 +0000 (+0100) Subject: doc/sod.sty, doc/*.tex: Put optional explicit name right before synopsis. X-Git-Url: https://git.distorted.org.uk/~mdw/sod/commitdiff_plain/34042b3558b28b85fa7155f7c7cd171239cbbaa3?hp=c06ba2665a64bff825193af71416ccb4811cf204 doc/sod.sty, doc/*.tex: Put optional explicit name right before synopsis. This makes the argument order better, and also clears space at the start of the argument list for a different optional thing. --- diff --git a/doc/parsing.tex b/doc/parsing.tex index 4386b4c..4cb6ef1 100644 --- a/doc/parsing.tex +++ b/doc/parsing.tex @@ -673,10 +673,10 @@ file-location protocols. \begin{describe}{parseform}{char @} \end{describe} -\begin{describe}[char]{parse}{@} +\begin{describe}{parse}[char]{@} \end{describe} -\begin{describe}[string]{parse}{@} +\begin{describe}{parse}[string]{@} \end{describe} \begin{describe}{parse}{:any} @@ -706,7 +706,7 @@ file-location protocols. \begin{describe}{parseform}{token @ @[@@] @[:peekp @@]} \end{describe} -\begin{describe}[atom]{parse}{@} +\begin{describe}{parse}[atom]{@} \end{describe} \begin{describe}{cls}{scanner-context () \&key :scanner} diff --git a/doc/runtime.tex b/doc/runtime.tex index 2e04639..a8abf85 100644 --- a/doc/runtime.tex +++ b/doc/runtime.tex @@ -42,7 +42,7 @@ calling functions which make use of keyword arguments; see \xref{sec:concepts.ke The header file defines two simple structure types, and a function type which will be described later. -\begin{describe}[struct kwval]{type} +\begin{describe}{type}[struct kwval] {struct kwval \{ \\ \ind const char *kw; \\ const void *val; \-\\ @@ -55,7 +55,7 @@ will be described later. the actual argument type.) \end{describe} -\begin{describe}[struct kwtab]{type} +\begin{describe}{type}[struct kwtab] {struct kwtab \{ \\ \ind const struct kwval *v; \\ size_t n; \-\\ @@ -136,7 +136,7 @@ result will be unbounded recursion or some other bad outcome. The following macros are intended to help with constructing keyword argument lists. Their use is not essential, but may help prevent errors. -\begin{describe}[KWARGS]{mac}{KWARGS(@)} +\begin{describe}{mac}[KWARGS]{KWARGS(@)} The @ encloses a sequence of keyword arguments expressed as calls to argument consists of a sequence of calls to the keyword-argument macros described below, one after another without any separation. @@ -158,18 +158,18 @@ lists. Their use is not essential, but may help prevent errors. The following keyword-argument macros can be used within the @|KWARGS| @ argument. -\begin{describe}[K]{mac}{K(@, @)} +\begin{describe}{mac}[K]{K(@, @)} Passes a keyword @ and its corresponding @, as a pair of arguments. The @ should be a single identifier (not a quoted string). The @ may be any C expression of the appropriate type. \end{describe} -\begin{describe}[K_VALIST]{mac}{K_VALIST(@)} +\begin{describe}{mac}[K_VALIST]{K_VALIST(@)} Passes an indirect variable-length argument tail. The argument @ should be an lvalue of type @|va_list|, which will be passed by reference. \end{describe} -\begin{describe}[K_TAB]{mac}{K_TAB(@, @)} +\begin{describe}{mac}[K_TAB]{K_TAB(@, @)} Passes a vector of keyword arguments. The argument @ should be the base address of the vector, and @ should be the number of elements in the vector. @@ -261,7 +261,7 @@ definitions of functions which accept keyword arguments. The following macros define data types and functions used for collecting keyword arguments. -\begin{describe}[KWSET_STRUCT]{mac}{KWSET_STRUCT(@);} +\begin{describe}{mac}[KWSET_STRUCT]{KWSET_STRUCT(@);} The @|KWSET_STRUCT| macro defines a \emph{keyword structure} named @|struct @{}_kwargs|. For each argument defined in the keyword set, this structure contains two members: one has exactly the @ and @ @@ -269,7 +269,7 @@ keyword arguments. type @|unsigned int| named @|@{}_suppliedp|. \end{describe} -\begin{describe}[KWDECL]{mac} +\begin{describe}{mac}[KWDECL] {@ KWDECL(@, @);} The macro declares and initializes a keyword argument structure variable named @ for the named keyword @. The optional @@ -279,7 +279,7 @@ keyword arguments. corresponding defaults from the keyword-set definition. \end{describe} -\begin{describe}[KWSET_PARSEFN]{mac} +\begin{describe}{mac}[KWSET_PARSEFN] {@ KWSET_PARSEFN(@)} The macro @|KWSET_PARSEFN| defines a keyword argument \emph{parser @@ -344,7 +344,7 @@ keyword arguments. The following macros make use of the definitions described above to actually make a function's keyword arguments available to it. -\begin{describe}[KW_PARSE]{mac}{KW_PARSE(@, @, @);} +\begin{describe}{mac}[KW_PARSE]{KW_PARSE(@, @, @);} The @|KW_PARSE| macro invokes a keyword argument parsing function. The @ argument should name a keyword set; @ should be an lvalue of type @|struct @{}_kwargs|; and @ should be the name of the @@ -365,7 +365,7 @@ make a function's keyword arguments available to it. appropriately. \end{describe} -\begin{describe}[KWPARSE]{mac}{KWPARSE(@);} +\begin{describe}{mac}[KWPARSE]{KWPARSE(@);} The macro @|KWPARSE| (note the lack of underscore) combines \descref{KWDECL}{mac} and \descref{KW_PARSE}{mac}. It declares and initializes a keyword argument structure variable with the fixed name @@ -395,7 +395,7 @@ mechanism, and it's useful to be able to define a function which doesn't currently accept any keywords, but which might in the future be extended to allow keyword arguments. -\begin{describe}[KW_PARSE_EMPTY]{mac}{KW_PARSE_EMPTY(@, @);} +\begin{describe}{mac}[KW_PARSE_EMPTY]{KW_PARSE_EMPTY(@, @);} This is an analogue to \descref{KW_PARSE}{mac} which checks the keyword argument list for a function which accepts no keyword arguments. @@ -410,14 +410,14 @@ allow keyword arguments. other than the special predefined ones. \end{describe} -\begin{describe}[KWPARSE_EMPTY]{mac}{KWPARSE_EMPTY(@);} +\begin{describe}{mac}[KWPARSE_EMPTY]{KWPARSE_EMPTY(@);} This is an analogue to \descref{KWPARSE}{mac} which checks that the enclosing function has been passed no keyword arguments other than the special predefined ones. It assumes that the first keyword name is in an argument named @|kwfirst_|, as set up by the \descref{KWTAIL}[marker]{mac}. \end{describe} -\begin{describe}[kw_parseempty]{fun} +\begin{describe}{fun}[kw_parseempty] {void kw_parseempty% (\=const char *@, const char *@, va_list *@, \+\\ @@ -449,11 +449,11 @@ depending on the corresponding @`_suppliedp' flags. A few macros are provided to make this task easier. -\begin{describe}[KW_COUNT]{mac}{KW_COUNT(@)} +\begin{describe}{mac}[KW_COUNT]{KW_COUNT(@)} Returns the number of keywords defined in a keyword set named @. \end{describe} -\begin{describe}[KW_COPY]{mac} +\begin{describe}{mac}[KW_COPY] {KW_COPY(@, @, @, @, @);} The macro @|KW_COPY| populates a vector of @|kwval| structures from a @@ -494,7 +494,7 @@ In this situation, the parser functions generated by \descref{KWSET_PARSEFN}{mac} (and the \descref{kw_parseempty}[function]{fun}) call @|kw_unknown|. -\begin{describe}[kw_unknown]{fun} +\begin{describe}{fun}[kw_unknown] {void kw_unknown(const char *@, const char *@);} This is a function of two arguments: @ points to the name of the @@ -508,7 +508,7 @@ call @|kw_unknown|. message to the standard error stream and calls \man{abort}{3}. \end{describe} -\begin{describe}[kw_unkhookfn]{type} +\begin{describe}{type}[kw_unkhookfn] {typedef void kw_unkhookfn(const char *@, const char *@);} The @|kw_unkhookfn| type is the type of unknown-keyword handler functions. @@ -517,7 +517,7 @@ call @|kw_unknown|. and @ is the name of the offending unknown keyword. \end{describe} -\begin{describe}[kw_unkhook]{var}{kw_unkhookfn *kw_unkhook} +\begin{describe}{var}[kw_unkhook]{kw_unkhookfn *kw_unkhook} This variable\footnote{% Having a single global hook variable is obviously inadequate for a modern library, but dealing with multiple threads isn't currently possible @@ -537,7 +537,7 @@ call @|kw_unknown|. \descref{kw_defunknown}[function]{fun}. \end{describe} -\begin{describe}[kw_defunknown]{fun} +\begin{describe}{fun}[kw_defunknown] {void kw_defunknown(const char *@, const char *@);} This function simply writes a message to standard error, to the effect that the keyword named by @ is not known in the keyword set @, and @@ -608,7 +608,7 @@ translator. Others may find them useful for special effects, but they can be tricky to understand and use correctly and can't really be recommended for general use. -\begin{describe}[SOD_OFFSETDIFF]{mac} +\begin{describe}{mac}[SOD_OFFSETDIFF] {ptrdiff_t SOD_OFFSETDIFF(@, @_1, @_2);} Returns the signed offset between two members of a structure or union type. @@ -621,7 +621,7 @@ general use. to be very useful elsewhere. \end{describe} -\begin{describe}[SOD_ILAYOUT]{mac} +\begin{describe}{mac}[SOD_ILAYOUT] {@{}__ilayout *SOD_ILAYOUT(@, @, const void *@);} Recovers the instance layout base address from a pointer to one of its instance chains. @@ -639,7 +639,7 @@ general use. @|SOD_INSTBASE| macro (described below) is more suited to general use. \end{describe} -\begin{describe}[SOD_INSTBASE]{mac}{void *SOD_INSTBASE(const @ *@)} +\begin{describe}{mac}[SOD_INSTBASE]{void *SOD_INSTBASE(const @ *@)} Finds the base address of an instance's layout. Given a pointer @ to an instance, @|SOD_INSTBASE| returns the base @@ -657,7 +657,7 @@ general use. The following macros and functions query the runtime relationships between instances and classes. -\begin{describe}[SOD_CLASSOF]{mac} +\begin{describe}{mac}[SOD_CLASSOF] {const SodClass *SOD_CLASSOF(const @ *@);} Returns the class object describing an instance's dynamic class. @@ -667,7 +667,7 @@ instances and classes. for @ itself, it's called @|@{}__class|.) \end{describe} -\begin{describe}[sod_subclassp]{fun} +\begin{describe}{fun}[sod_subclassp] {int sod_subclassp(const SodClass *@, const SodClass *@);} Decide whether one class @ is actually a subclass of another class @@ -687,7 +687,7 @@ The following macros and functions are used to convert instance pointers of some (static) type into instance pointers of other static types to the same instance. -\begin{describe}[SOD_XCHAIN]{mac} +\begin{describe}{mac}[SOD_XCHAIN] {void *SOD_XCHAIN(@, const @ *@);} Performs a `cross-chain upcast'. @@ -702,9 +702,9 @@ instance. \end{describe} \begin{describe*} - {\dhead[SOD_CONVERT]{mac} + {\dhead{mac}[SOD_CONVERT] {@ *SOD_CONVERT(@, const void *@);} - \dhead[sod_convert]{fun} + \dhead{fun}[sod_convert] {void *sod_convert(const SodClass *@, const void *@);}} Perform general conversions (up-, down-, and cross-casts) on instance pointers. @@ -741,11 +741,11 @@ allocation strategies. They don't concern themselves with allocation or deallocation, and applications are free to use any suitable mechanism. \begin{describe*} - {\dhead[SOD_INIT]{mac} + {\dhead{mac}[SOD_INIT] {@ *SOD_INIT(@, void *@

, @);} - \dhead[sod_init]{fun} + \dhead{fun}[sod_init] {void *sod_init(const SodClass *@, void *@

, \dots);} - \dhead[sod_initv]{fun} + \dhead{fun}[sod_initv] {void *sod_initv(const SodClass *@, void *@

, va_list @);}} Imprints and initializes an instance of a class @ in the storage starting at address~@

. @@ -767,7 +767,7 @@ deallocation, and applications are free to use any suitable mechanism. \xref{sec:structures.layout.instance}. \end{describe*} -\begin{describe}[sod_teardown]{fun}{int sod_teardown(void *@

);} +\begin{describe}{fun}[sod_teardown]{int sod_teardown(void *@

);} Tears down an instance of a class, releasing any resources it holds. This function is a very thin wrapper around sending the @|obj.teardown| @@ -779,7 +779,7 @@ deallocation, and applications are free to use any suitable mechanism. \subsubsection{Automatic storage duration} The following macro constructs an instance with automatic storage duration. -\begin{describe}[SOD_DECL]{mac}{SOD_DECL(@, @, @);} +\begin{describe}{mac}[SOD_DECL]{SOD_DECL(@, @, @);} Declares and initializes an instance with automatic storage duration. Given a class name @ and an identifier @, @|SOD_DECL| declares @@ -804,9 +804,9 @@ standard C heap. They don't work in freestanding implementations where @|malloc| and @|free| are not available. \begin{describe*} - {\dhead[SOD_MAKE]{mac}{@ *SOD_MAKE(@, @);} - \dhead[sod_make]{fun}{void *sod_make(const SodClass *@, \dots);} - \dhead[sod_makev]{fun} + {\dhead{mac}[SOD_MAKE]{@ *SOD_MAKE(@, @);} + \dhead{fun}[sod_make]{void *sod_make(const SodClass *@, \dots);} + \dhead{fun}[sod_makev] {void *sod_makev(const SodClass *@, va_list @);}} Constructs and returns a pointer to a new instance of @. @@ -830,7 +830,7 @@ standard C heap. They don't work in freestanding implementations where probably be used where possible. \end{describe*} -\begin{describe}[sod_destroy]{fun}{int sod_destroy(void *@

);} +\begin{describe}{fun}[sod_destroy]{int sod_destroy(void *@

);} Tears down and frees an instance allocated using @|malloc|. The pointer @

should be an instance pointer, i.e., a pointer to any of diff --git a/doc/sod.sty b/doc/sod.sty index 7f777ea..9ff6181 100644 --- a/doc/sod.sty +++ b/doc/sod.sty @@ -211,13 +211,13 @@ \def\q@{\q@} -%% \parse@dhd{NEXT}[NAME]{CAT}{SYNOPSIS} +%% \parse@dhd{NEXT}{CAT}[NAME]{SYNOPSIS} %% call NEXT{CAT}{NAME}{SYNOPSIS} %% #1 #2 #3 -\def\parse@dhd#1{% {NEXT} - \@ifnextchar[{\parse@dhd@cc{#1}}{\parse@dhd@cd{#1}}} -\def\parse@dhd@cc#1[#2]#3#4{% {NEXT}[NAME]{CAT}{SYNOPSIS} - #1{#3}{#2}{#4}} +\def\parse@dhd#1#2{% {NEXT}{CAT} + \@ifnextchar[{\parse@dhd@cc{#1}{#2}}{\parse@dhd@cd{#1}{#2}}} +\def\parse@dhd@cc#1#2[#3]#4{% {NEXT}{CAT}[NAME]{SYNOPSIS} + #1{#2}{#3}{#4}} \def\parse@dhd@cd#1#2#3{% {NEXT}{CAT}{SYNOPSIS} \parse@dhd@ce{#1}{#2}{#3}#3 \q@} \def\parse@dhd@ce#1#2#3#4 #5\q@{% diff --git a/doc/structures.tex b/doc/structures.tex index 37ca9e3..d4690f8 100644 --- a/doc/structures.tex +++ b/doc/structures.tex @@ -45,7 +45,7 @@ structure. Instance chains contain slots and vtable pointers, as described below. All instances have the basic structure of a @|struct sod_instance|. -\begin{describe}[struct sod_instance]{type} +\begin{describe}{type}[struct sod_instance] {struct sod_instance \{ \\ \ind const struct sod_vtable *_vt; \-\\ \};} @@ -57,7 +57,7 @@ instances have the basic structure of a @|struct sod_instance|. \end{description} \end{describe} -\begin{describe}[struct sod_vtable]{type} +\begin{describe}{type}[struct sod_vtable] {struct sod_vtable \{ \\ \ind const SodClass *_class; \\ size_t _base; \-\\ @@ -118,7 +118,7 @@ recommended. \label{fig:structures.root.sodobject} \end{figure} -\begin{describe}[SodObject]{cls} +\begin{describe}{cls}[SodObject] {[nick = obj, metaclass = SodClass, lisp_metaclass = sod_class] \\ class SodObject \{ \\ \ind @@ -139,7 +139,7 @@ recommended. The following messages are defined. - \begin{describe}[obj.init]{msg}{void init(?);} + \begin{describe}{msg}[obj.init]{void init(?);} Initialize a newly allocated instance. This message uses a custom method combination which works like the @@ -171,7 +171,7 @@ recommended. \xref{sec:concepts.lifecycle.birth}. \end{describe} - \begin{describe}[obj.teardown]{msg}{int teardown();} + \begin{describe}{msg}[obj.teardown]{int teardown();} Teardown an instance which is no longer required. The message returns an integer flag. A zero value means that the @@ -199,7 +199,7 @@ recommended. \subsection{The SodClass class} \label{sec:structures.root.sodclass} -\begin{describe}[SodClass]{cls} +\begin{describe}{cls}[SodClass] {[nick = cls, link = SodObject] \\ class SodClass: SodObject \{ \\ \ind const char *name; \\ @@ -289,7 +289,7 @@ recommended. \end{description} \end{describe} -\begin{describe}[struct sod_chain]{type} +\begin{describe}{type}[struct sod_chain] {struct sod_chain \{ \\ \ind size_t n_classes; \\ const SodClass *const *classes; \\