docs: explain new seqMain.c feature

documentation/Compiling.txt

@@ -36,8 +36,8 @@ Option  Description
   +l    Add line markers to the generated code, so that C compiler
         messages refer to the SNL source file. This is the default.
   -l    Do not produce line markers.
-  +m    Generate a main procedure for a stand-alone program.
-  -m    Do not generate a main procedure. This is the default.
+  +m    Include main procedure (seqMain.c) for a stand-alone program.
+  -m    Do not include seqMain.c. This is the default.
   +s    :ref:`Safe mode`: variables are local to state set
         and must be communicated explicitly. Implies +r.
   -s    Traditional (non-safe) mode. This is the default for
@@ -50,8 +50,8 @@ Option  Description
 ======  ===============================================================
 
 Note that :option:`+a` and :option:`-a` are ignored for calls to
-:c:func:`pvGet` that explicitly specify ``SYNC`` or ``ASYNC`` in the 2nd
-argument.
+:c:func:`pvGet` that explicitly specify ``SYNC`` or ``ASYNC`` in the
+2nd argument.
 
 Options may also be set from within the program (somewhere between the
 program name/parameter and the state set definitions), see
@@ -79,8 +79,8 @@ knows (and cares) about C is the syntax. This means that many errors
 will only be found only during the C compilation phase. The C compiler
 will attributed these to the corresponding location in the SNL source
 file, since by default *snc* generates line markers in the output that
-point back to the original source. This can be turned off with the :option:`-l`
-("ell") compiler switch.
+point back to the original source. This can be turned off with the
+:option:`-l` ("ell") compiler switch.
 
 Warnings
 ^^^^^^^^
@@ -101,11 +101,11 @@ C Pre-processor
 ---------------
 
 Depending on the application, it might be useful to pre-process the SNL
-source with a C pre-processor (*cpp*). Using the C pre-processor
-allows you to include other SNL files, define macros, and perform
-conditional compilation. *snc* supports this by interpreting
-*cpp*-generated line markers, so that error and warning messages
-refer to the line numbers in the un-pre-processed SNL source.
+source with a C pre-processor (*cpp*). Using the C pre-processor allows
+you to include other SNL files, define macros, and perform conditional
+compilation. *snc* supports this by interpreting *cpp*-generated line
+markers, so that error and warning messages refer to the line numbers
+in the un-pre-processed SNL source.
 
 Complete Build
 --------------
@@ -163,60 +163,29 @@ executable), or create a library for an IOC.
 
 .. todo:: explain what libraries to link and where to find them
 
-Building a Stand-alone Program for Unix
----------------------------------------
-
-Under Unix, either the :option:`+m` compiler option should be used to
-create a C main program or else the programmer should write a main
-program (the main program plays the same role as the VxWorks
-startup script).
-
-Here is a full build of a simple state program from source under
-Solaris. Compiler and loader options will vary with other operating
-systems. It is assumed that the sequencer is in
-*/usr/local/epics/seq* and that EPICS is in */usr/local/epics*. ::
-
-  gcc -E -x c demo.st >demo.i
-  snc +m demo.i
-
-  gcc -D_POSIX_C_SOURCE=199506L -D_POSIX_THREADS -D_REENTRANT\
-  -D__EXTENSIONS__ -DnoExceptionsFromCXX \
-  -DOSITHREAD_USE_DEFAULT_STACK \
-  -I. -I.. \
-  -I/usr/local/epics/seq/include \
-  -I/usr/local/epics/base/include/os/solaris \
-  -I/usr/local/epics/base/include -c demo.c
-  g++ -o demo \
-  -L/usr/local/epics/seq/lib/solaris-sparc \
-  -L/usr/local/epics/base/lib/solaris-sparc \
-  demo.o -lseq -lpv -lpvCa -lca -lCom \
-  -lposix4 -lpthread -lthread -lsocket -lnsl -lm
-
-The main program generated by the :option:`+m` compiler option is very
-simple. Currently it looks like this::
-
-    int main(int argc,char *argv[]) {
-        char * macro_def;
-        int callIocsh = 0;
-
-        if(argc>1 && strcmp(argv[1],"-s")==0) {
-            callIocsh=1;
-            --argc; ++argv;
-        }
-        macro_def = (argc>1)?argv[1]:NULL;
-        seq(&StringArray, macro_def, 0);
-        if(callIocsh) {
-            seqRegisterSequencerCommands();
-            seqRegisterSequencerProgram (&StringArray);
-            iocsh(0);
-        } else {
-            epicsThreadExitMain();
-        }
-        return(0);
-    }
-
-
-.. _UsingmakeBaseApp:
+.. _Building a Stand-alone Program:
+
+Building a Stand-alone Program
+------------------------------
+
+The :option:`+m` compiler option can be used to create a stand-alone program,
+otherwise an iocshell is needed to start sequencer programs. Since version 2.1
+the main procedure is no longer hard-coded. Instead, the code generator adds a
+define and an include statement ::
+
+   #define PROG_NAME name_of_your_snl_program
+   #include "seqMain.c"
+
+at the end of the generated C file, where ``name_of_your_snl_program`` is the
+name (identifier) whose address is to be passed to the ``seq`` function. This means you can provide your own version of main
+simply by placing a file named ``seqMain.c`` in your source directory (the
+EPICS build system usually takes care that the source directory is at the front
+of the C compiler's include path).
+
+A simple default ``seqMain.c`` is provided and installed into the sequencer's
+``include`` directory. Note that since version 2.1 the default main starts an
+ioc shell; this can be disabled by providing a ``-S`` (capital 's') argument.
+The old ``-s`` switch is accepted for backward compatibility but does nothing.
 
 Using makeBaseApp
 -----------------
@@ -244,5 +213,5 @@ All that's left to do is add::
 
    SNCSEQ=/path/to/your/seq/installation
 
-to ``configure/RELEASE`` (that is, the one in the ``configure`` directory
-that ``makeBaseApp.pl`` just created).
+to ``configure/RELEASE`` (that is, the one in the ``configure``
+directory that ``makeBaseApp.pl`` just created).

documentation/Introduction.txt

@@ -199,6 +199,9 @@ ad hoc way variable types were handled before. The new code is not *that*
 much more complicated and it is certainly easier to extend with new
 features.
 
+The main procedure (:option:`+m`) is no longer hard-coded, so you can easily
+provide your own version. See :ref:`Building a Stand-alone Program`.
+
 Lofts of minor fixes.
 
 In the sequencer library interface, bitMask is now a synonym for unsigned,