On Feb 8, 2013, at 2:27 PM, Hannes Magnusson wrote: > On Thu, Feb 7, 2013 at 6:54 PM, Philip Olson <phi...@roshambo.org> wrote: >> >> On Feb 7, 2013, at 5:36 PM, Hannes Magnusson wrote: >> >>> On Mon, Feb 4, 2013 at 12:34 AM, Philip Olson <phi...@roshambo.org> wrote: >>> >>>> >>>> As for what to do, I recommend: >>>> >>>> a) We add <methodsynopsis> to all SPL aliases >>>> b) Be certain that every "Class synopsis" page is accurate >>> >>> So this came up the other day when someone filed a bug report about >>> not finding php.net/_ . >>> This fix was to manually hack it into the search iirc. >>> >>> I'm pretty sure the real fix to all aliases as methodsynopsis. They >>> would then be listed automatically correctly, pointing to their >>> parents page, and would be indexed by PhD. >> >> I'm not sure what you mean. Do you mean adding an XML file >> for every alias? For all aliases? Like the permanent ones >> (_.xml), deprecated ones (mysql-dbname.xml), and those that >> have been removed? Or maybe you mean (d) from the previous >> email? > > > gmp_div is an alias for gmp_div_q. > gmp_div has it own .xml file. > > If we remove that file, and simply add the <methodsynopsis> into > gmp-div-q.xml so that file now has two. > > We can mark it as role="alias" or whatever.
Good idea, although I wonder how we should differentiate how the aliases are presented. For example, nobody should use mysql_dbname() so listing it would be confusing and add clutter, but listing the likes of _() next to gettext() is okay and desired. Maybe we could implement an attribute. Now the following is NOT a proposal, but: role="alias" status="deprecated" Status might be too generic but its possible values might be: removed : it was removed, as per the changelog deprecated : presented in a "do not use this, will die in future" way discouraged: presented in a "do not use this" way equal : will always exist hidden : we decided to hide it for some other reason? While this appears overly complex, the point is there are different types of aliases and that this difference should be clear to the user. And do it in a way that is easy to manage (i.e., content won't become too outdated). This sort of structure would allow QA tools/scripts to help monitor, and generate lists if needed. Also there are a few places where we reverse the two, where we document the function as an alias, and vice versa, because the preference leans towards the "aliased" function. I can't think of one now but know they exist. So we'll also need to agree that this little lie is okay? :) >>> These random inline notes, and dedicated page for aliases listing >>> seems like a total wtf to me. >> >> >> I'm not sure what this means. Which inline notes? And I >> do not think a page listing aliases is a WTF but maybe >> I am missing the meaning. Do you mean WTF because it's so >> outdated? >> > > Some pages like php.net/_ have a note in the <refsect role="notes"> > that there are aliases to this function. > But thats the only way to find that out. > Other pages have are almost blank php.net/ftp_quit with just a quick > note that this is an alias. > > So aliases are totally inconsistent right now. But I think we should > add the aliased functions <methodsynopsis> into their > actual-function-name.xml file. Agreed, they have become inconsistent (and outdated) in many ways and a goal is to fix that. Thoughts on the different types of aliases? Regards, Philip
