docs: Internals Book improvements (02)

.github/workflows/docs.yml

@@ -22,6 +22,8 @@ jobs:
         run: pip install -r docs/requirements.txt
       - name: Check formatting
         run: make -C docs check-formatting
+      - name: Build
+        run: make -C docs html
       - name: Publish
         if: github.event_name == 'push'
         uses: sphinx-notes/pages@v3

docs-old/output-api.md

@@ -3,108 +3,110 @@
 Everything now resides beneath the php_output namespace, and there's an API call
 for every output handler op.
 
-    Checking output control layers status:
-        // Using OG()
-        php_output_get_status();
-
-    Starting the default output handler:
-        // php_start_ob_buffer(NULL, 0, 1);
-        php_output_start_default();
-
-    Starting an user handler by zval:
-        // php_start_ob_buffer(zhandler, chunk_size, erase);
-        php_output_start_user(zhandler, chunk_size, flags);
-
-    Starting an internal handler without context:
-        // php_ob_set_internal_handler(my_php_output_handler_func_t, buffer_size, "output handler name", erase);
-        php_output_start_internal(handler_name, handler_name_len, my_php_output_handler_func_t, chunk_size, flags);
-
-    Starting an internal handler with context:
-        // not possible with old API
-        php_output_handler *h;
-        h = php_output_handler_create_internal(handler_name, handler_name_len, my_php_output_handler_context_func_t, chunk_size, flags);
-        php_output_handler_set_context(h, my_context, my_context_dtor);
-        php_output_handler_start(h);
-
-    Testing whether a certain output handler has already been started:
-        // php_ob_handler_used("output handler name");
-        php_output_handler_started(handler_name, handler_name_len);
-
-    Flushing one output buffer:
-        // php_end_ob_buffer(1, 1);
-        php_output_flush();
-
-    Flushing all output buffers:
-        // not possible with old API
-        php_output_flush_all();
-
-    Cleaning one output buffer:
-        // php_ob_end_buffer(0, 1);
-        php_output_clean();
-
-    Cleaning all output buffers:
-        // not possible with old API
-        php_output_clean_all();
-
-    Discarding one output buffer:
-        // php_ob_end_buffer(0, 0);
-        php_output_discard();
-
-    Discarding all output buffers:
-        // php_ob_end_buffers(0);
-        php_output_discard_all();
-
-    Stopping (and dropping) one output buffer:
-        // php_ob_end_buffer(1, 0)
-        php_output_end();
-
-    Stopping (and dropping) all output buffers:
-        // php_ob_end_buffers(1, 0);
-        php_output_end_all();
-
-    Retrieving output buffers contents:
-        // php_ob_get_buffer(zstring);
-        php_output_get_contents(zstring);
-
-    Retrieving output buffers length:
-        // php_ob_get_length(zlength);
-        php_output_get_length(zlength);
-
-    Retrieving output buffering level:
-        // OG(nesting_level);
-        php_output_get_level();
-
-    Issue a warning because of an output handler conflict:
-        // php_ob_init_conflict("to be started handler name", "to be tested if already started handler name");
-        php_output_handler_conflict(new_handler_name, new_handler_name_len, set_handler_name, set_handler_name_len);
-
-    Registering a conflict checking function, which will be checked prior starting the handler:
-        // not possible with old API, unless hardcoding into output.c
-        php_output_handler_conflict_register(handler_name, handler_name_len, my_php_output_handler_conflict_check_t);
-
-    Registering a reverse conflict checking function, which will be checked prior starting the specified foreign handler:
-        // not possible with old API
-        php_output_handler_reverse_conflict_register(foreign_handler_name, foreign_handler_name_len, my_php_output_handler_conflict_check_t);
-
-    Facilitating a context from within an output handler callable with ob_start():
-        // not possible with old API
-        php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ, (void *) &custom_ctx_ptr_ptr);
-
-    Disabling of the output handler by itself:
-        //not possible with old API
-        php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_DISABLE, NULL);
-
-    Marking an output handler immutable by itself because of irreversibility of its operation:
-        // not possible with old API
-        php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE, NULL);
-
-    Restarting the output handler because of a CLEAN operation:
-        // not possible with old API
-        if (flags & PHP_OUTPUT_HANDLER_CLEAN) { ... }
-
-    Recognizing by the output handler itself if it gets discarded:
-        // not possible with old API
-        if ((flags & PHP_OUTPUT_HANDLER_CLEAN) && (flags & PHP_OUTPUT_HANDLER_FINAL)) { ... }
+```
+Checking output control layers status:
+    // Using OG()
+    php_output_get_status();
+
+Starting the default output handler:
+    // php_start_ob_buffer(NULL, 0, 1);
+    php_output_start_default();
+
+Starting an user handler by zval:
+    // php_start_ob_buffer(zhandler, chunk_size, erase);
+    php_output_start_user(zhandler, chunk_size, flags);
+
+Starting an internal handler without context:
+    // php_ob_set_internal_handler(my_php_output_handler_func_t, buffer_size, "output handler name", erase);
+    php_output_start_internal(handler_name, handler_name_len, my_php_output_handler_func_t, chunk_size, flags);
+
+Starting an internal handler with context:
+    // not possible with old API
+    php_output_handler *h;
+    h = php_output_handler_create_internal(handler_name, handler_name_len, my_php_output_handler_context_func_t, chunk_size, flags);
+    php_output_handler_set_context(h, my_context, my_context_dtor);
+    php_output_handler_start(h);
+
+Testing whether a certain output handler has already been started:
+    // php_ob_handler_used("output handler name");
+    php_output_handler_started(handler_name, handler_name_len);
+
+Flushing one output buffer:
+    // php_end_ob_buffer(1, 1);
+    php_output_flush();
+
+Flushing all output buffers:
+    // not possible with old API
+    php_output_flush_all();
+
+Cleaning one output buffer:
+    // php_ob_end_buffer(0, 1);
+    php_output_clean();
+
+Cleaning all output buffers:
+    // not possible with old API
+    php_output_clean_all();
+
+Discarding one output buffer:
+    // php_ob_end_buffer(0, 0);
+    php_output_discard();
+
+Discarding all output buffers:
+    // php_ob_end_buffers(0);
+    php_output_discard_all();
+
+Stopping (and dropping) one output buffer:
+    // php_ob_end_buffer(1, 0)
+    php_output_end();
+
+Stopping (and dropping) all output buffers:
+    // php_ob_end_buffers(1, 0);
+    php_output_end_all();
+
+Retrieving output buffers contents:
+    // php_ob_get_buffer(zstring);
+    php_output_get_contents(zstring);
+
+Retrieving output buffers length:
+    // php_ob_get_length(zlength);
+    php_output_get_length(zlength);
+
+Retrieving output buffering level:
+    // OG(nesting_level);
+    php_output_get_level();
+
+Issue a warning because of an output handler conflict:
+    // php_ob_init_conflict("to be started handler name", "to be tested if already started handler name");
+    php_output_handler_conflict(new_handler_name, new_handler_name_len, set_handler_name, set_handler_name_len);
+
+Registering a conflict checking function, which will be checked prior starting the handler:
+    // not possible with old API, unless hardcoding into output.c
+    php_output_handler_conflict_register(handler_name, handler_name_len, my_php_output_handler_conflict_check_t);
+
+Registering a reverse conflict checking function, which will be checked prior starting the specified foreign handler:
+    // not possible with old API
+    php_output_handler_reverse_conflict_register(foreign_handler_name, foreign_handler_name_len, my_php_output_handler_conflict_check_t);
+
+Facilitating a context from within an output handler callable with ob_start():
+    // not possible with old API
+    php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ, (void *) &custom_ctx_ptr_ptr);
+
+Disabling of the output handler by itself:
+    //not possible with old API
+    php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_DISABLE, NULL);
+
+Marking an output handler immutable by itself because of irreversibility of its operation:
+    // not possible with old API
+    php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE, NULL);
+
+Restarting the output handler because of a CLEAN operation:
+    // not possible with old API
+    if (flags & PHP_OUTPUT_HANDLER_CLEAN) { ... }
+
+Recognizing by the output handler itself if it gets discarded:
+    // not possible with old API
+    if ((flags & PHP_OUTPUT_HANDLER_CLEAN) && (flags & PHP_OUTPUT_HANDLER_FINAL)) { ... }
+```
 
 ## Output handler hooks
 
@@ -113,23 +115,25 @@ remove the CLEANABLE and REMOVABLE bits when the first output has passed through
 or handlers implemented in C to be used with ob_start() can contain a non-global
 context:
 
-    PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ
-        pass a void*** pointer as second arg to receive the address of a pointer
-        pointer to the opaque field of the output handler context
-    PHP_OUTPUT_HANDLER_HOOK_GET_FLAGS
-        pass a int* pointer as second arg to receive the flags set for the output handler
-    PHP_OUTPUT_HANDLER_HOOK_GET_LEVEL
-        pass a int* pointer as second arg to receive the level of this output handler
-        (starts with 0)
-    PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE
-        the second arg is ignored; marks the output handler to be neither cleanable
-        nor removable
-    PHP_OUTPUT_HANDLER_HOOK_DISABLE
-        the second arg is ignored; marks the output handler as disabled
+```
+PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ
+    pass a void*** pointer as second arg to receive the address of a pointer
+    pointer to the opaque field of the output handler context
+PHP_OUTPUT_HANDLER_HOOK_GET_FLAGS
+    pass a int* pointer as second arg to receive the flags set for the output handler
+PHP_OUTPUT_HANDLER_HOOK_GET_LEVEL
+    pass a int* pointer as second arg to receive the level of this output handler
+    (starts with 0)
+PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE
+    the second arg is ignored; marks the output handler to be neither cleanable
+    nor removable
+PHP_OUTPUT_HANDLER_HOOK_DISABLE
+    the second arg is ignored; marks the output handler as disabled
+```
 
 ## Open questions
 
-* Should the userland API be adjusted and unified?
+- Should the userland API be adjusted and unified?
 
 Many bits of the manual (and very first implementation) do not comply with the
 behaviour of the current (to be obsoleted) code, thus should the manual or the

docs-old/parameter-parsing-api.md

@@ -24,7 +24,7 @@ int zend_parse_parameters_ex(int flags, int num_args, char *type_spec, ...);
 
 The `zend_parse_parameters()` function takes the number of parameters passed to
 the extension function, the type specifier string, and the list of pointers to
-variables to store the results in. The _ex() version also takes 'flags' argument
+variables to store the results in. The \_ex() version also takes 'flags' argument
 -- current only `ZEND_PARSE_PARAMS_QUIET` can be used as 'flags' to specify that
 the function should operate quietly and not output any error messages.
 
@@ -61,7 +61,7 @@ See also
 The following list shows the type specifier, its meaning, and the parameter types
 that need to be passed by address. All passed parameters are set if the PHP
 parameter is non-optional and untouched if optional and the parameter is not
-present. The only exception is O where the zend_class_entry* has to be provided
+present. The only exception is O where the zend_class_entry\* has to be provided
 on input and is used to verify the PHP parameter is an instance of that class.
 
 ```txt
@@ -96,18 +96,18 @@ z  - the actual zval (zval*)
 
 The following characters also have a meaning in the specifier string:
 
-* `|` - indicates that the remaining parameters are optional, they should be
+- `|` - indicates that the remaining parameters are optional, they should be
   initialized to default values by the extension since they will not be touched
   by the parsing function if they are not passed to it.
-* `/` - use SEPARATE_ZVAL() on the parameter it follows
-* `!` - the parameter it follows can be of specified type or NULL. If NULL is
+- `/` - use SEPARATE_ZVAL() on the parameter it follows
+- `!` - the parameter it follows can be of specified type or NULL. If NULL is
   passed, and the output for such type is a pointer, then the output pointer is
   set to a native NULL pointer. For 'b', 'l' and 'd', an extra argument of type
-  bool* must be passed after the corresponding bool*, zend_long* or
-  double* arguments, respectively. A non-zero value will be written to the
+  bool\* must be passed after the corresponding bool\*, zend_long\* or
+  double\* arguments, respectively. A non-zero value will be written to the
   bool if a PHP NULL is passed.
-  For `f` use the ``ZEND_FCI_INITIALIZED(fci)`` macro to check if a callable
-  has been provided and ``!ZEND_FCI_INITIALIZED(fci)`` to check if a PHP NULL
+  For `f` use the `ZEND_FCI_INITIALIZED(fci)` macro to check if a callable
+  has been provided and `!ZEND_FCI_INITIALIZED(fci)` to check if a PHP NULL
   is passed.
 
 ## Note on 64bit compatibility
@@ -119,15 +119,15 @@ and `size_t` to strings length (i.e. for "s" you need to pass char `*` and
 
 Both mistakes might cause memory corruptions and segfaults:
 
-* 1
+- 1
 
 ```c
 char *str;
 long str_len; /* XXX THIS IS WRONG!! Use size_t instead. */
 zend_parse_parameters(ZEND_NUM_ARGS(), "s", &str, &str_len)
 ```
 
-* 2
+- 2
 
 ```c
 int num; /* XXX THIS IS WRONG!! Use zend_long instead. */

docs-old/self-contained-extensions.md

@@ -3,21 +3,23 @@
 A self-contained extension can be distributed independently of the PHP source.
 To create such an extension, two things are required:
 
-* Configuration file (config.m4)
-* Source code for your module
+- Configuration file (config.m4)
+- Source code for your module
 
 We will describe now how to create these and how to put things together.
 
 ## Preparing your system
 
 While the result will run on any system, a developer's setup needs these tools:
 
-* GNU autoconf
-* GNU m4
+- GNU autoconf
+- GNU m4
 
 All of these are available from
 
-    ftp://ftp.gnu.org/pub/gnu/
+```
+ftp://ftp.gnu.org/pub/gnu/
+```
 
 ## Converting an existing extension
 
@@ -144,10 +146,10 @@ an existing module called `foo`.
    automatically be able to use `--with-foo=shared[,..]` or
    `--enable-foo=shared[,..]`.
 
-2. In `config.m4`, use `PHP_NEW_EXTENSION([foo],.., [$ext_shared])` to enable
+1. In `config.m4`, use `PHP_NEW_EXTENSION([foo],.., [$ext_shared])` to enable
    building the extension.
 
-3. Add the following lines to your C source file:
+1. Add the following lines to your C source file:
 
 ```c
 #ifdef COMPILE_DL_FOO
@@ -162,7 +164,7 @@ points to be regarded.
 
 1. Add `LICENSE` or `COPYING` to the `package.xml`
 
-2. The following should be defined in one of the extension header files
+1. The following should be defined in one of the extension header files
 
 ```c
 #define PHP_FOO_VERSION "1.2.3"