On Wed, Feb 13, 2013 at 2:50 PM, Philip Olson <phi...@roshambo.org> wrote: > > 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.
Sounds good. Anyone with a full list of aliases we can experiment this on? If all works out cool maybe we can do this for method<->function aliases to not duplicate our documentation work, but to list them problem in the rendered version for our users. -Hannes
