docs(web): update optscript.rst (in progress)

Signed-off-by: Masatake YAMATO <[email protected]>

Author: masatake

docs/optscript.rst

@@ -19,28 +19,29 @@ operators of Optscript and PostScript are the same. You can get the
 basic knowledge for using Optscript from the materials for learning
 PostScript.
 
-"PostScript Language Tutorial & Cookbook" published by Adobe Systems
-Inc. The book is known as "blue book". This is the best place to
+"PostScript Language Tutorial & Cookbook" is a book published by Adobe
+Systems Inc. The book, known as "blue book", is the best place to
 start.  PostScript is a language for controlling printers. So it has
-many graphical operators. Optscript is for tagging, and doesn't have
-such graphical operators. So you can skip the sections about graphics
+many graphical operators. Optscript doesn't have such graphical
+operators. So you can skip the sections about graphics
 (but you may want to read them because the book is written well).
 
 Ghostscript (``gs`` or ``gsnd``) is an interpreter for the PostScript
 language and PDF files. Unlike Optscript, it implements the full-set of
 PostScript features including graphical operators. It is available
-under either the GNU GPL Affero license. You can Ghostscript while
+under either the GNU GPL Affero license. You can use Ghostscript while
 reading the blue book. Do web searching to know about Ghostscript.
 
-``optscript`` is an command that source files are included in
-Universal Ctags source tree. You can use it as the replacement of
-``gs``. However, I recommend you to have ``gs`` at hand because
-``optscript`` may have bugs. ``gs`` is much mature than ``optscript``.
-Having two interpreters helps you to know correct behavior.
+``optscript`` is a command that source files are included in the
+source tree of Universal Ctags. You can use it as the replacement of
+``gs`` to learn PostScript. However, I recommend you to have ``gs`` at
+hand because ``optscript`` may have bugs. ``gs`` is much mature than
+``optscript``. Having two interpreters helps you to know expected
+behavior of the language.
 
 Though ``gs`` has much higher qualities than ``optscript``, eventually
 you may have to build the ``optscript`` command to learn Optscript
-specific operators. You can built the command with "``make
+specific operators for tagging. You can built the command with "``make
 optscript``".
 
 * red book
@@ -164,9 +165,29 @@ easily, Python sessions doing the same as Optscript are also written.
 	>>> add5_and_print(4)
 	9
 
-* string manipulation
+* String manipulation
+
+  - Comparison
+
+	Optscript:
+
+	.. code-block:: console
+
+	   OPT> (abc) (efg) eq { (same) = } { (different) = } ifelse
+	   different
+	   OPT> (abc) (abc) eq { (same) = } { (different) = } ifelse
+	   same
+
+	Python:
+
+	.. code-block:: console
+
+		>>> if 'abc' == 'efg':
+		...   print ('same')
+		... else:
+		...   print ('different')
+		different
 
-  TBW
 
 * array manipulation
 
@@ -190,6 +211,8 @@ easily, Python sessions doing the same as Optscript are also written.
 
 Optscript in ctags
 ~~~~~~~~~~~~~~~~~~
+Optscript executable in ctags assumes that all tags are in the corkQueue and
+they have corkIndexes. See ":ref:`output-tag-stream`" about corkQueue and corkIndexes.
 
 Related options
 ...............
@@ -242,12 +265,12 @@ TBW: two timings of evaluation
 
 Put code fragments at the end of options with surrounding "``{{``" and
 "``}}``". Though it is not impossible, a command line is not suitable
-place to put code fragments because the code fragments may be long.
-Instead, you should write them to a .ctags file.
+place to write code fragments because the options with code fragments
+may be too long. Instead, you should write them to your .ctags file.
 
-.. warning::  An important rule in writing Optscript code in a file is
-  the start marker, ``{{`` must be at the end of line, and the end
-  marker ``}}`` must be at the beginning of line. If you break the
+.. warning:: An important rule in writing Optscript code in a .ctags
+  file is the start marker, ``{{``, must be at the end of line, and the
+  end marker, ``}}``, must be at the beginning of line. If you break the
   rule, the optlib loader of ctags fails to read your file.
 
 ``--_prelude-<LANG>`` is for specified code fragments run at the
@@ -269,62 +292,139 @@ represents the field has an operator for reading
 (``:fieldname``). ``w`` represents the field has an operator for
 writing (``fieldname:``).
 
+``optlib2c``, a translator from .ctags file to C language source file
+supports the code framents. Some of optlib parsers integrated to
+Universal Ctags already use Optscript. You can find practical
+examples of Optscript in files in ``optlib`` directory. The positional
+rules about `{{` and `}}` is applicable to ``optlib2c``.
+
+Data types
+..........
+
+Non-standard data types for tagging are added.  You can use it only in
+``ctags`` command, not in ``optscript`` command.
+
+``matchloc``
+
+	This opaque data type is for representing a position in a source
+	file. The name is an acronym for "match location".  ``_matchloc``
+	pushes a ``matchloc`` object to ``ostack``.
+
+``corkIndex:int`` or ``index:int``
+
+	This represents a corkIndex. ``.`` pushes the corkIndex for a tag
+	just created with the option owning the code frament.
+
+``tag``
+
+	This represents a tag data structure which is not in the corkQueue
+	yet. ``_tag`` is an operator pushing a ``tag`` object to
+	``ostack``. ``_commit`` puts the ``tag`` object on ``ostack`` to
+	the corkQueue, and pushes an integer as a corkIndex.
+
 Operators
 ............................
 
 **.** -> ``-`` **.** ``corkIndex:int``
 
-    Push the cork index for the tag
+	Push the cork index for the tag
 
 **\\n** -> ``-`` **\\n** ``matchedString:string``
 
-	``n`` is an integer (0...9) representing a group in a pattern.
+	``n`` is an integer (1...9) representing a group in a pattern.
 	Push the matched string for the group.
 
 ``_matchloc``
 
-    TBW
+	TBW
 
 ``:field`` (See the output of ``--_list-operators``)
 
-    Get the value for the specified field from a tag
+	Get the value for the specified field from a tag
 	and put it.
 
 ``field:`` (See the output of ``--_list-operators``)
 
-    Set a value at the stack to the specified field of a tag.
+	Set a value at the stack to the specified field of a tag.
 
 ``_tag``
 
-    TBW
+	TBW
 
-``_COMMIT``
+``_commit``
 
-    TBW
+	TBW
 
 ``_traced``
 
-    TBW
+	TBW
 
-Data types
-..........
 
-``MATCHLOC``
+Recipes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    TBW
+Arrange the name of a tag
+...........................................
 
-``index:int``
+"input.foo":
 
-    TBW
+.. code-block::
 
-``TAG``
+	def a
+	def b
 
-    TBW
+Goal: If a language specific extra ``extendedName`` is given, the
+parser for input.foo emits extra tags having ``X`` as prefix.
 
-Recipes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The base version of .ctags ("foo0.ctags"):
+
+.. code-block:: ctags
+
+	--langdef=foo
+	--map-foo=.foo
+	--kinddef-foo=d,definition,definitions
+	--regex-foo=/^def[ \t]+([a-z]+)/\1/d/
+
+The tags output ("output0.tags") for the base version
+with "``--optoins=foo0.ctags input.foo``":
+
+.. code-block:: tags
+
+   a	input.foo	/^def a$/;"	d
+   b	input.foo	/^def b$/;"	d
+
+The Optscript version of .ctags ("foo1.ctags") for achieving the goal:
+
+.. code-block:: ctags
+
+	--langdef=foo
+	--map-foo=.foo
+	--kinddef-foo=d,definition,definitions
+	--_extradef-foo=extendedName, tags prefixed with X
+	--regex-foo=/^def[ \t]+([a-z]+)/\1/d/{{
+	    /foo.extendedName _extraenabled {
+	        mark \1 ?X _buildstring % name, \1 + 'X'
+		    /definition             % kind
+		    1 _matchloc             % location for \1
+		    _tag                    % a tag object is pushed.
+		    % ostack => tag
+		    dup
+		    % ostack => tag tag
+		    /foo.extendedName _markextra
+		    % ostack => tag
+		    _commit
+	    } if
+	}}
+
+The tags output ("output1.tags") for the Optscript version
+with "``--optoins=foo1.ctags --extras-foo=+'{extendedName}' input.foo``":
+
+.. code-block:: tags
 
-TBW
+   a	input.foo	/^def a$/;"	d
+   aX	input.foo	/^def a$/;"	d
+   b	input.foo	/^def b$/;"	d
+   bX	input.foo	/^def b$/;"	d
 
 Difference between Optscript and PostScript
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~