Re: Control structure manual pages using sect instead of refsect
| From: | G. P. B. | Date: | Thu, 20 Jun 2019 14:22:09 +0000 |
| Subject: | Re: Control structure manual pages using sect instead of refsect | ||
| References: | 1 2 | Groups: | php.doc |
| Request: | Send a blank email to phpdoc+get-969387287@lists.php.net to get a copy of this message | ||
On Thu, 20 Jun 2019 at 16:13, Peter Cowburn <petercowburn@gmail.com> wrote:
> On Thu, 20 Jun 2019 at 13:58, G. P. B. <george.banyard@gmail.com> wrote:
>
>> Hello doc team,
>>
>> I couldn't come up with a better subject but it seems that all the manual
>> pages in language/control-structures/ use `
<sect1>`
>> as the usual
>> `<refentry>` one.
>> Is this something which should be changed or is there a reason as to why
>> it uses sect1 ?
>>
>
> 1. Not unless there's a problem.
> 2. Nope.
>
Not sure if it is a problem per se, but I wanted to improve the page
talking about include [1], mostly making it more visible that it's possible
to assign a variable to an include construct if the file included returns.
By wanting to do this I realized that the See Also section is just a
sentence and doesn't conform to the usual way the doc is structured and
this seems to be because usually this is a refsec element.
Also, I suppose if we change the structure we could add an Error/Exception
section to describe the behavior on a failed include.
So I suppose the final question is, can this be done without changing the
sect1 and if so how. And if not should we go about "modernizing" these
pages to conform to the usual XML structure?
Best regards
George P. Banyard