Re: Changing our function definition syntax in the manual

On Tue, Nov 10, 2015 at 11:04 PM, Levi Morrison <levim@php.net> wrote: > I am talking about the PHD rendering system, yes (though not > necessarily the file/commit you linked). > > To clarify, the XML for strpos looks like this: > > <methodsynopsis> > <type>mixed</type><methodname>strpos</methodname> > > <methodparam><type>string</type><parameter>haystack</parameter></methodparam> > > <methodparam><type>mixed</type><parameter>needle</parameter></methodparam> > <methodparam > > choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam> > </methodsynopsis> > > The XML does not need to change; in fact the schema doesn't allow for > a trailing return type[1]. Instead we need to change how we render the > XML to put the return type at the end. > > The difficulty in this is that the renderer is essentially rendering > things recursively; I'm not familiar enough with the system to > identify a methodsynopsis and to render it and its children in some > other way and preventing it from recursing. > > Does that make sense? > > [1]: http://www.docbook.org/tdg/en/html/methodsynopsis.html > > > On Tue, Nov 10, 2015 at 2:57 PM, Sherif Ramadan <theanomaly.is@gmail.com> wrote: >> Levi, >> >> Are you referring to >> >>http://git.php.net/?p=phd.git;a=blob;f=phpdotnet/phd/Format/Abstract/XHTML.php;h=6232cfc288c9d92fd537312ecd6bbf65e37144e9;hb=HEAD >> ? >> >> On Tue, Nov 10, 2015 at 4:38 PM, Levi Morrison <levim@php.net> wrote: >>> >>> You don't need to change the XML, just the renderer. This is much >>> easier than changing the sources but still would take a bit of time to >>> figure out the proper way to do with our renderer. I looked into doing >>> it myself but then I got busy with life. >>> >>> On Tue, Nov 10, 2015 at 2:23 PM, Sherif Ramadan <theanomaly.is@gmail.com> >>> wrote: >>> > Also, I dislike the idea of having inconsistent formats in the >>> > prototypes >>> > across functions. There are a handful of PHP 7 specific functions. Why >>> > have >>> > disparity? It only serves to irritate people in the log run on where to >>> > look >>> > for return types in the rototype header. >>> > >>> > If we do a mass change across the board for all functions I have to >>> > agree >>> > with Adam's assessment that it's not so trivial with the CSS we >>> > currently >>> > have. >>> > >>> > You have to change the DTD as well as the XML in all of the >>> > function/method >>> > pages. There's also the CHM builds which I know nothing about and then >>> > yea, >>> > translations. That's potentially hundreds of thousands of files changed. >>> > >>> > Seems like a lot of work for merely moving a return type from the left >>> > of >>> > the prototype to its right. And the net gain is merely being consistent >>> > with >>> > language syntax? The docs have never really been consistent there >>> > anyway. We >>> > still have missing visibility specifiers in some method signatures if I >>> > recall correctly. I'd say those are more worth while fixing first. >>> > >>> > >>> > >>> > On Tue, Nov 10, 2015 at 3:47 PM, Adam Harvey <aharvey@php.net> wrote: >>> >> >>> >> On 10 November 2015 at 12:19, Julien Pauli <jpauli@php.net> wrote: >>> >> > The twitt (https://twitter.com/tvlooy/status/664109119343878144) was >>> >> > about why don't we show function syntax for description using the >>> >> > new >>> >> > declaration syntax used in PHP 7 parser ? >>> >> >>> >> I had this on my list of things to look at when I was on my migration >>> >> guide tear a couple of months back, but then totally forgot. >>> >> >>> >> I think it'd be a nice to have, but I don't see a great option for >>> >> implementing it. Doing it purely in CSS would be ideal, but the markup >>> >> we currently generate doesn't really allow for that: you can't float >>> >> the return type right because the container is full width, and using >>> >> flexbox to reorder causes unfixable spacing issues due to the fact we >>> >> have inline text (for things like the parentheses around parameters) >>> >> that we can't add padding to (since switching .methodsynopsis to >>> >> display: flex collapses all the whitespace within it, which is >>> >> important for formatting). >>> >> >>> >> It feels like the only viable options are: >>> >> >>> >> 1. Changing PhD to emit another, semantically unimportant element >>> >> inside .methodsynopsis that we can style as an inline-block, then >>> >> float the return type right. >>> >> >>> >> 2. Changing every function/method page in the manual to reorder where >>> >> the return type appears, then have PhD insert the colon in the right >>> >> place. >>> >> >>> >> I don't really love either. I dislike option 2 more than option 1; it >>> >> feels like a lot of churn for little benefit, and all translations >>> >> would have to make the same mechanical change. (Presumably it could be >>> >> mostly scripted, but it's still a pain.) >>> >> >>> >> All that said, since I've been out of the Web development game for a >>> >> while now: what am I missing? >>> >> >>> >> Adam >>> > >>> > >> >> I would say that it was just a suggestion, if some minds are against, or if it's technically not trivial to implement, let's forget about it. (I thought it'd be easier :-p ). Julien.Pauli