Re: Changing our function definition syntax in the manual

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 > >