Re: Control structure manual pages using sect instead of refsect
| From: | G. P. B. | Date: | Sun, 23 Jun 2019 19:51:27 +0000 |
| Subject: | Re: Control structure manual pages using sect instead of refsect | ||
| References: | 1 2 3 | Groups: | php.doc |
| Request: | Send a blank email to phpdoc+get-969387289@lists.php.net to get a copy of this message | ||
On Thu, 20 Jun 2019 at 16:22, G. P. B. <george.banyard@gmail.com> wrote:
> 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
>
So I looked up all the sources from all languages and they are (now) all up
to date for the include page, would it be reasonable to change the
structure, update all languages with the EN-Revision tag and then put in
place my improvements?
George P. Banyard