Re: Adding since-version tags to the docs?

Поиск
Список
Период
Сортировка
От Shulgin, Oleksandr
Тема Re: Adding since-version tags to the docs?
Дата
Msg-id CACACo5SMdjcZ+3Wu+brxgvZtdSwzEpMTuyJ7oAs9LfCC8JnEpw@mail.gmail.com
обсуждение исходный текст
Ответ на Re: Adding since-version tags to the docs?  (Anastasia Lubennikova <a.lubennikova@postgrespro.ru>)
Список pgsql-hackers
On Mon, Aug 31, 2015 at 3:17 PM, Anastasia Lubennikova <a.lubennikova@postgrespro.ru> wrote:
31.08.2015 14:06, Shulgin, Oleksandr пишет:

Hello,

I often find it pity that our docs are missing any information on since when a certain GUC setting, SQL-level command or function was introduced.

Clicking through the "this page in other versions" links at the top of a webpage does help, but you still need to do some guessing (binary search?) with the clicks. :-)

It would be nice if we could make a script that would parse the sgml files and for every symbol it finds it would add a tag like "Since version 9.x".  Such a script could start by checking out REL9_0_STABLE and looking through all symbols it can find, tagging them "Since 9.0".  Then it could commit the result, check out the next version branch and apply said commit (some manual effort to merge it might be required), and repeat the process, assuming all newly found symbols must be introduced in this new version.

That is for the lists, tabular representation might require adding a new column, I'm not sure what would be the best format.

After this process is done once, we can have a requirement that every newly introduced symbol/command be tagged manually by the patch author.

Do you think such approach will work?  Is there interest in having this done?

--
Alex

I think that you're looking for Feature matrix.

Thanks, that might come handy sometime.

Though what I'm really up to is a direct statement in the documentation, like the Python stdlib docs do.  I find it really helpful then you read about a command or a function you might want to use to know immediately that it was added in like 9.3 and you still have to support 9.1 in your code, things like that.

Actually, Python docs go further by providing distinct "New in version X.Y" and "Changed in version X.Y: ..." to describe behavior change when that does happen, like new parameters being added, etc.  This we cannot extract automatically for sure, but I think such cases are rare enough and usually get a notice anyway.

--
Alex

В списке pgsql-hackers по дате отправления:

Предыдущее
От: Andreas Karlsson
Дата:
Сообщение: Re: Commitfest remaining "Needs Review" items
Следующее
От: "Shulgin, Oleksandr"
Дата:
Сообщение: Re: Adding since-version tags to the docs?