Skip to content

Commit 12257c5

Browse files
GirgiasGirgias
authored
Update templates for documentation pages (#166)
1 parent b2de125 commit 12257c5

22 files changed

+423
-406
lines changed

‎scripts/docgen/book.developer.tpl

+2-2
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,9 @@
3939

4040
<preface xml:id="intro.{EXT_NAME_ID}">
4141
&reftitle.intro;
42-
<para>
42+
<simpara>
4343

44-
</para>
44+
</simpara>
4545
</preface>
4646

4747
&reference.{EXT_NAME_ID}.setup;

‎scripts/docgen/book.tpl

+3-3
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,9 @@
55

66
<preface xml:id="intro.{EXT_NAME_ID}">
77
&reftitle.intro;
8-
<para>
9-
10-
</para>
8+
<simpara>
9+
Extension introduction.
10+
</simpara>
1111
</preface>
1212

1313
&reference.{EXT_NAME_ID}.setup;

‎scripts/docgen/class.tpl

+2-2
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@
88
<!-- {{{ {CLASS_NAME} intro -->
99
<section xml:id="{CLASS_NAME_ID}.intro">
1010
&reftitle.intro;
11-
<para>
11+
<simpara>
1212

13-
</para>
13+
</simpara>
1414
</section>
1515
<!-- }}} -->
1616

‎scripts/docgen/constructor.tpl

+4-4
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@
1111
{MODIFIERS}{RETURN_TYPE}<methodname>{FULL_METHOD_NAME}</methodname>
1212
{METHOD_PARAMETERS}
1313
</constructorsynopsis>
14-
<para>
14+
<simpara>
1515

16-
</para>
16+
</simpara>
1717

1818
&warn.undocumented.func;
1919

@@ -29,9 +29,9 @@
2929
example, because there's also a procedural version of the method).
3030
<refsect1 role="returnvalues">
3131
&reftitle.returnvalues;
32-
<para>
32+
<simpara>
3333
34-
</para>
34+
</simpara>
3535
</refsect1>
3636
-->
3737

‎scripts/docgen/docgen.php

+47-50
Original file line numberDiff line numberDiff line change
@@ -331,9 +331,9 @@ function create_markup_to_parameter_section(Reflector $obj, $content) { /* {{{ *
331331
$markup .= str_repeat(' ', $ident + 1) ."<varlistentry>". PHP_EOL;
332332
$markup .= str_repeat(' ', $ident + 2) .'<term><parameter>'. ($param->getName() ? $param->getName() : 'param'. $count) ."</parameter></term>". PHP_EOL;
333333
$markup .= str_repeat(' ', $ident + 2) ."<listitem>". PHP_EOL;
334-
$markup .= str_repeat(' ', $ident + 3) ."<para>". PHP_EOL;
334+
$markup .= str_repeat(' ', $ident + 3) ."<simpara>". PHP_EOL;
335335
$markup .= str_repeat(' ', $ident + 4) . PHP_EOL;
336-
$markup .= str_repeat(' ', $ident + 3) ."</para>". PHP_EOL;
336+
$markup .= str_repeat(' ', $ident + 3) ."</simpara>". PHP_EOL;
337337
$markup .= str_repeat(' ', $ident + 2) ."</listitem>". PHP_EOL;
338338
$markup .= str_repeat(' ', $ident + 1) ."</varlistentry>". PHP_EOL;
339339

@@ -344,7 +344,7 @@ function create_markup_to_parameter_section(Reflector $obj, $content) { /* {{{ *
344344
$content = preg_replace('/\{PARAMETERS_DESCRIPTION\}/', $markup, $content, 1);
345345
}
346346
} else {
347-
$content = preg_replace('/\{'. $param_name .'\}/', '<void />', $content, 1);
347+
$content = preg_replace('/\{'. $param_name .'\}/', '<void/>', $content, 1);
348348
$content = preg_replace('/\{PARAMETERS_DESCRIPTION\}/', '&no.function.parameters;', $content, 1);
349349
}
350350

@@ -424,17 +424,16 @@ function gen_mapping_markup(ReflectionMethod $method, ReflectionFunction $functi
424424
$method_params[] = $param->getName();
425425
}
426426

427-
$markup = "<para>". PHP_EOL;
428-
$markup .= str_repeat(' ', $ident + 1) ."<variablelist>". PHP_EOL;
427+
$markup = str_repeat(' ', $ident) ."<variablelist>". PHP_EOL;
429428
foreach ($func_params as $param) {
430-
$markup .= str_repeat(' ', $ident + 2) ."<varlistentry>". PHP_EOL;
431-
$markup .= str_repeat(' ', $ident + 3) .'<term><parameter>'. ($param ? $param : 'param'. $count) ."</parameter></term>". PHP_EOL;
432-
$markup .= str_repeat(' ', $ident + 3) ."<listitem>". PHP_EOL;
433-
$markup .= str_repeat(' ', $ident + 4) ."<para>". PHP_EOL;
434-
$markup .= str_repeat(' ', $ident + 5) . PHP_EOL;
435-
$markup .= str_repeat(' ', $ident + 4) ."</para>". PHP_EOL;
436-
$markup .= str_repeat(' ', $ident + 3) ."</listitem>". PHP_EOL;
437-
$markup .= str_repeat(' ', $ident + 2) ."</varlistentry>". PHP_EOL;
429+
$markup .= str_repeat(' ', $ident + 1) ."<varlistentry>". PHP_EOL;
430+
$markup .= str_repeat(' ', $ident + 2) .'<term><parameter>'. ($param ? $param : 'param'. $count) ."</parameter></term>". PHP_EOL;
431+
$markup .= str_repeat(' ', $ident + 2) ."<listitem>". PHP_EOL;
432+
$markup .= str_repeat(' ', $ident + 3) ."<simpara>". PHP_EOL;
433+
$markup .= str_repeat(' ', $ident + 4) . PHP_EOL;
434+
$markup .= str_repeat(' ', $ident + 3) ."</simpara>". PHP_EOL;
435+
$markup .= str_repeat(' ', $ident + 2) ."</listitem>". PHP_EOL;
436+
$markup .= str_repeat(' ', $ident + 1) ."</varlistentry>". PHP_EOL;
438437
$count++;
439438
}
440439
$diff_params = array_diff($method_params, $func_params);
@@ -443,23 +442,22 @@ function gen_mapping_markup(ReflectionMethod $method, ReflectionFunction $functi
443442
if (!($param && in_array($param, $diff_params))) {
444443
continue;
445444
}
446-
$markup .= str_repeat(' ', $ident + 2) ."<varlistentry>". PHP_EOL;
447-
$markup .= str_repeat(' ', $ident + 3) .'<term><parameter>'. ($param ? $param : 'param'. $count) ."</parameter></term>". PHP_EOL;
448-
$markup .= str_repeat(' ', $ident + 3) ."<listitem>". PHP_EOL;
449-
$markup .= str_repeat(' ', $ident + 4) ."<para>". PHP_EOL;
450-
$markup .= str_repeat(' ', $ident + 5) . PHP_EOL;
451-
$markup .= str_repeat(' ', $ident + 4) ."</para>". PHP_EOL;
452-
$markup .= str_repeat(' ', $ident + 3) ."</listitem>". PHP_EOL;
453-
$markup .= str_repeat(' ', $ident + 2) ."</varlistentry>". PHP_EOL;
445+
$markup .= str_repeat(' ', $ident + 1) ."<varlistentry>". PHP_EOL;
446+
$markup .= str_repeat(' ', $ident + 2) .'<term><parameter>'. ($param ? $param : 'param'. $count) ."</parameter></term>". PHP_EOL;
447+
$markup .= str_repeat(' ', $ident + 2) ."<listitem>". PHP_EOL;
448+
$markup .= str_repeat(' ', $ident + 3) ."<simpara>". PHP_EOL;
449+
$markup .= str_repeat(' ', $ident + 4) . PHP_EOL;
450+
$markup .= str_repeat(' ', $ident + 3) ."</simpara>". PHP_EOL;
451+
$markup .= str_repeat(' ', $ident + 2) ."</listitem>". PHP_EOL;
452+
$markup .= str_repeat(' ', $ident + 1) ."</varlistentry>". PHP_EOL;
454453
$count++;
455454
}
456-
$markup .= str_repeat(' ', $ident + 1) ."</variablelist>". PHP_EOL;
457-
$markup .= str_repeat(' ', $ident) ."</para>";
455+
$markup .= str_repeat(' ', $ident) ."</variablelist>". PHP_EOL;
458456

459457
$content = preg_replace('/\{PARAMETERS_DESCRIPTION\}/', $markup, $content, 1);
460458
}
461459
} else {
462-
$content = preg_replace('/\{PARAMETERS\}/', '<void />', $content, 1);
460+
$content = preg_replace('/\{PARAMETERS\}/', '<void/>', $content, 1);
463461
$content = preg_replace('/\{PARAMETERS_DESCRIPTION\}/', '&no.function.parameters;', $content, 1);
464462
}
465463

@@ -470,6 +468,7 @@ function gen_mapping_markup(ReflectionMethod $method, ReflectionFunction $functi
470468
}
471469
/* }}} */
472470

471+
/* TODO This is outdated */
473472
function gen_class_markup(ReflectionClass $class, $content) { /* {{{ */
474473
$id = format_id($class->getName());
475474
$escapedName = addslashes($class->getName());
@@ -554,7 +553,7 @@ function gen_class_markup(ReflectionClass $class, $content) { /* {{{ */
554553
$markup .= str_repeat(' ', $ident + 2) .'<varlistentry xml:id="'. $id .".constants.". format_id($constant) ."\">". PHP_EOL;
555554
$markup .= str_repeat(' ', $ident + 3) .'<term><constant>'. $class->getName() .'::'. $constant ."</constant></term>". PHP_EOL;
556555
$markup .= str_repeat(' ', $ident + 3) ."<listitem>". PHP_EOL;
557-
$markup .= str_repeat(' ', $ident + 4) ."<para></para>". PHP_EOL;
556+
$markup .= str_repeat(' ', $ident + 4) ."<simpara></simpara>". PHP_EOL;
558557
$markup .= str_repeat(' ', $ident + 3) ."</listitem>". PHP_EOL;
559558
$markup .= str_repeat(' ', $ident + 2) ."</varlistentry>". PHP_EOL . PHP_EOL;
560559
}
@@ -629,7 +628,7 @@ function gen_class_markup(ReflectionClass $class, $content) { /* {{{ */
629628
$markup .= str_repeat(' ', $ident + 2) .'<varlistentry xml:id="'. $id .'.props.'. format_id($property->getName()) ."\">". PHP_EOL;
630629
$markup .= str_repeat(' ', $ident + 3) .'<term><varname>'. $property->getName() ."</varname></term>". PHP_EOL;
631630
$markup .= str_repeat(' ', $ident + 3) ."<listitem>". PHP_EOL;
632-
$markup .= str_repeat(' ', $ident + 4) ."<para></para>". PHP_EOL;
631+
$markup .= str_repeat(' ', $ident + 4) ."<simpara></simpara>". PHP_EOL;
633632
$markup .= str_repeat(' ', $ident + 3) ."</listitem>". PHP_EOL;
634633
$markup .= str_repeat(' ', $ident + 2) ."</varlistentry>". PHP_EOL;
635634
}
@@ -703,9 +702,9 @@ function gen_extension_markup(ReflectionExtension $obj, $content, $xml_file) { /
703702
$markup2 .= str_repeat(' ', $ident + 2) ."<type>". get_type_by_string($value['global_value']) ."</type>". PHP_EOL;
704703
$markup2 .= str_repeat(' ', $ident + 1) ."</term>". PHP_EOL;
705704
$markup2 .= str_repeat(' ', $ident + 1) ."<listitem>". PHP_EOL;
706-
$markup2 .= str_repeat(' ', $ident + 2) ."<para>". PHP_EOL;
705+
$markup2 .= str_repeat(' ', $ident + 2) ."<simpara>". PHP_EOL;
707706
$markup2 .= str_repeat(' ', $ident + 3) . PHP_EOL;
708-
$markup2 .= str_repeat(' ', $ident + 2) ."</para>". PHP_EOL;
707+
$markup2 .= str_repeat(' ', $ident + 2) ."</simpara>". PHP_EOL;
709708
$markup2 .= str_repeat(' ', $ident + 1) ."</listitem>". PHP_EOL;
710709
$markup2 .= str_repeat(' ', $ident) ."</varlistentry>". PHP_EOL;
711710
}
@@ -727,24 +726,22 @@ function gen_extension_markup(ReflectionExtension $obj, $content, $xml_file) { /
727726
$ident = get_ident_size('CONSTANTS', $content);
728727

729728
$markup = "&extension.constants;". PHP_EOL;
730-
$markup .= str_repeat(' ', $ident) ."<para>". PHP_EOL;
731-
$markup .= str_repeat(' ', $ident + 1) ."<variablelist>". PHP_EOL;
729+
$markup .= str_repeat(' ', $ident) ."<variablelist>". PHP_EOL;
732730

733731
foreach ($constants as $name => $value) {
734-
$markup .= str_repeat(' ', $ident + 2) .'<varlistentry xml:id="constant.'. format_id($name) .'">'. PHP_EOL;
735-
$markup .= str_repeat(' ', $ident + 3) ."<term>". PHP_EOL;
736-
$markup .= str_repeat(' ', $ident + 4) ."<constant>". $name ."</constant>". PHP_EOL;
737-
$markup .= str_repeat(' ', $ident + 4) ."(". get_xml_type_tag_or_entity($value, true) .")". PHP_EOL;
738-
$markup .= str_repeat(' ', $ident + 3) ."</term>". PHP_EOL;
739-
$markup .= str_repeat(' ', $ident + 3) ."<listitem>". PHP_EOL;
740-
$markup .= str_repeat(' ', $ident + 4) ."<simpara>". PHP_EOL;
741-
$markup .= str_repeat(' ', $ident + 4) ."</simpara>". PHP_EOL;
742-
$markup .= str_repeat(' ', $ident + 3) ."</listitem>". PHP_EOL;
743-
$markup .= str_repeat(' ', $ident + 2) ."</varlistentry>". PHP_EOL;
732+
$markup .= str_repeat(' ', $ident + 1) .'<varlistentry xml:id="constant.'. format_id($name) .'">'. PHP_EOL;
733+
$markup .= str_repeat(' ', $ident + 2) ."<term>". PHP_EOL;
734+
$markup .= str_repeat(' ', $ident + 3) ."<constant>". $name ."</constant>". PHP_EOL;
735+
$markup .= str_repeat(' ', $ident + 3) ."(". get_xml_type_tag_or_entity($value, true) .")". PHP_EOL;
736+
$markup .= str_repeat(' ', $ident + 2) ."</term>". PHP_EOL;
737+
$markup .= str_repeat(' ', $ident + 2) ."<listitem>". PHP_EOL;
738+
$markup .= str_repeat(' ', $ident + 3) ."<simpara>". PHP_EOL;
739+
$markup .= str_repeat(' ', $ident + 3) ."</simpara>". PHP_EOL;
740+
$markup .= str_repeat(' ', $ident + 2) ."</listitem>". PHP_EOL;
741+
$markup .= str_repeat(' ', $ident + 1) ."</varlistentry>". PHP_EOL;
744742
}
745743

746-
$markup .= str_repeat(' ', $ident + 1) ."</variablelist>". PHP_EOL;
747-
$markup .= str_repeat(' ', $ident) ."</para>";
744+
$markup .= str_repeat(' ', $ident) ."</variablelist>". PHP_EOL;
748745

749746
$content = preg_replace('/\{CONSTANTS\}/', $markup, $content, 1);
750747
} else {
@@ -761,26 +758,26 @@ function gen_extension_markup(ReflectionExtension $obj, $content, $xml_file) { /
761758
$markup2 = '';
762759
if ($OPTION['pecl'] === true) {
763760

764-
$markup .= "<para>". PHP_EOL;
761+
$markup .= "<simpara>". PHP_EOL;
765762
$markup .= str_repeat(' ', $ident + 1) ."&pecl.info;". PHP_EOL;
766763
$markup .= str_repeat(' ', $ident + 1) ."<link xlink:href=\"&url.pecl.package;{EXT_NAME_ID}\">&url.pecl.package;{EXT_NAME_ID}</link>". PHP_EOL;
767-
$markup .= str_repeat(' ', $ident) . "</para>". PHP_EOL;
764+
$markup .= str_repeat(' ', $ident) . "</simpara>". PHP_EOL;
768765

769766
/*
770-
$markup2 .= "<para>". PHP_EOL;
767+
$markup2 .= "<simpara>". PHP_EOL;
771768
$markup2 .= str_repeat(' ', $ident2 + 1) ."The latest PECL/{EXT_NAME_ID} Win32 DLL is available here:". PHP_EOL;
772769
$markup2 .= str_repeat(' ', $ident2 + 1) ."<link xlink:href=\"&url.pecl.win.ext;php_{EXT_NAME_ID}.dll\">php_{EXT_NAME_ID}.dll</link>". PHP_EOL;
773-
$markup2 .= str_repeat(' ', $ident2) ."</para>". PHP_EOL;
770+
$markup2 .= str_repeat(' ', $ident2) ."</simpara>". PHP_EOL;
774771
*/
775772
} else {
776773

777-
$markup .= "<para>". PHP_EOL;
774+
$markup .= "<simpara>". PHP_EOL;
778775
$markup .= str_repeat(' ', $ident + 1) ."Use <option role=\"configure\">--with-{EXT_NAME_ID}[=DIR]</option> when compiling PHP.". PHP_EOL;
779-
$markup .= str_repeat(' ', $ident) ."</para>". PHP_EOL;
776+
$markup .= str_repeat(' ', $ident) ."</simpara>". PHP_EOL;
780777

781-
$markup2 .= "<para>". PHP_EOL;
778+
$markup2 .= "<simpara>". PHP_EOL;
782779
$markup2 .= str_repeat(' ', $ident2 + 1) ."Windows users should include <filename>php_{EXT_NAME_ID}.dll</filename> into &php.ini;". PHP_EOL;
783-
$markup2 .= str_repeat(' ', $ident2) ."</para>". PHP_EOL;
780+
$markup2 .= str_repeat(' ', $ident2) ."</simpara>". PHP_EOL;
784781
}
785782

786783
$content = str_replace('{EXT_INSTALL_MAIN}', $markup, $content);

‎scripts/docgen/function.tpl

+4-4
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@
1111
{RETURN_TYPE}<methodname>{FUNCTION_NAME}</methodname>
1212
{FUNCTION_PARAMETERS}
1313
</methodsynopsis>
14-
<para>
14+
<simpara>
1515

16-
</para>
16+
</simpara>
1717

1818
&warn.undocumented.func;
1919

@@ -26,9 +26,9 @@
2626

2727
<refsect1 role="returnvalues">
2828
&reftitle.returnvalues;
29-
<para>
29+
<simpara>
3030

31-
</para>
31+
</simpara>
3232
</refsect1>
3333
{DEFAULT_EXAMPLE}
3434
{DEFAULT_SEEALSO}

‎scripts/docgen/ini.tpl

+18-22
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,26 @@
22
<section xml:id="{EXT_NAME_ID}.configuration" xmlns="http://docbook.org/ns/docbook">
33
&reftitle.runtime;
44
&extension.runtime;
5-
<para>
6-
<table>
7-
<title>{EXT_NAME} &ConfigureOptions;</title>
8-
<tgroup cols="4">
9-
<thead>
10-
<row>
11-
<entry>&Name;</entry>
12-
<entry>&Default;</entry>
13-
<entry>&Changeable;</entry>
14-
<entry>&Changelog;</entry>
15-
</row>
16-
</thead>
17-
{INI_ENTRIES}
18-
</tgroup>
19-
</table>
20-
</para>
215

22-
&ini.descriptions.title;
6+
<table>
7+
<title>{EXT_NAME} &ConfigureOptions;</title>
8+
<tgroup cols="4">
9+
<thead>
10+
<row>
11+
<entry>&Name;</entry>
12+
<entry>&Default;</entry>
13+
<entry>&Changeable;</entry>
14+
<entry>&Changelog;</entry>
15+
</row>
16+
</thead>
17+
{INI_ENTRIES}
18+
</tgroup>
19+
</table>
2320

24-
<para>
25-
<variablelist>
26-
{INI_ENTRIES_DESCRIPTION}
27-
</variablelist>
28-
</para>
21+
<variablelist>
22+
&ini.descriptions.title;
23+
{INI_ENTRIES_DESCRIPTION}
24+
</variablelist>
2925
</section>
3026
<!-- Keep this comment at the end of the file
3127
Local variables:

‎scripts/docgen/mapping.tpl

+10-10
Original file line numberDiff line numberDiff line change
@@ -8,22 +8,22 @@
88

99
<refsect1 role="description">
1010
&reftitle.description;
11-
<para>&style.oop; (method):</para>
12-
<methodsynopsis>
11+
<simpara>&style.oop; (method):</simpara>
12+
<methodsynopsis>
1313
{MODIFIERS}{RETURN_TYPE}<methodname>{FULL_METHOD_NAME}</methodname>
1414
{METHOD_PARAMETERS}
15-
</methodsynopsis>
16-
<para>&style.procedural;:</para>
15+
</methodsynopsis>
16+
<simpara>&style.procedural;:</simpara>
1717
<methodsynopsis>
1818
<type>ReturnType</type><methodname>{FUNCTION_NAME}</methodname>
1919
{FUNCTION_PARAMETERS}
2020
</methodsynopsis>
21-
<para>
21+
<simpara>
2222

23-
</para>
23+
</simpara>
2424

2525
&warn.undocumented.func;
26-
26+
2727
</refsect1>
2828

2929
<refsect1 role="parameters">
@@ -33,9 +33,9 @@
3333

3434
<refsect1 role="returnvalues">
3535
&reftitle.returnvalues;
36-
<para>
37-
38-
</para>
36+
<simpara>
37+
38+
</simpara>
3939
</refsect1>
4040
{DEFAULT_EXAMPLE}
4141
{DEFAULT_SEEALSO}

‎scripts/docgen/method.tpl

+5-5
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@
1111
{MODIFIERS}{RETURN_TYPE}<methodname>{FULL_METHOD_NAME}</methodname>
1212
{METHOD_PARAMETERS}
1313
</methodsynopsis>
14-
<para>
14+
<simpara>
1515

16-
</para>
16+
</simpara>
1717

1818
&warn.undocumented.func;
1919

@@ -26,9 +26,9 @@
2626

2727
<refsect1 role="returnvalues">
2828
&reftitle.returnvalues;
29-
<para>
30-
31-
</para>
29+
<simpara>
30+
31+
</simpara>
3232
</refsect1>
3333
{DEFAULT_EXAMPLE}
3434
{DEFAULT_SEEALSO}

0 commit comments

Comments
 (0)