Re: [docbook] Re: [docbook-apps] proposed additions to DocBook for programming languages
Salut Thibaut, On 2019-04-29 5:38 p.m., Thibaut Cuvelier wrote: Hi Stefan, The two tag sets serve a similar purpose, but are very different in their implementation: the Boost-based set looks like an equivalent to refentry & co. (the base item is an API/library), while the one I proposed on GitHub is rather based on the synopses (the base item is either a class, an enumeration, a macro, or a namespace — the closest item to Boost root). Also, the Boost extension adds many many tags (77) ithout being similar to what already exists in DocBook, while mine tries to use fewer tags (18, 15 with a generic synopsisinfo) and to mimic the existing semantics. The final difference I see is that the Boost extension is really revolving around C++ (with concepts like headers, which are not present in that many languages), while I tried to be as language-agnostic as possible while being able to model as many things as possible. Just to highlight a few differences between both :). Actually, I had a look at BoostBook before choosing to design something else. I'm not going to argue on technical grounds for either side. However, I think it would be a big mistake to underestimate the importance of a community that is using a given technology, and thus is willing to help maintain it. BoostBuild is fully implemented and is part of the documentation toolchain used by many Boost components. Thus, when I mentored the project to migrate to DocBook 5 and eventually merge it into DocBook "mainstream", my hope was to enable the wider DocBook community to use it, making the tool and the project easier to maintain and evolve. This isn't a project to be taken on by a single person. Cordially, Stefan -- ...ich hab' noch einen Koffer in Berlin...
[docbook-apps] Re: [docbook] Re: [docbook-apps] proposed additions to DocBook for programming languages
Salut Thibaut, On 2019-04-29 5:38 p.m., Thibaut Cuvelier wrote: Hi Stefan, The two tag sets serve a similar purpose, but are very different in their implementation: the Boost-based set looks like an equivalent to refentry & co. (the base item is an API/library), while the one I proposed on GitHub is rather based on the synopses (the base item is either a class, an enumeration, a macro, or a namespace — the closest item to Boost root). Also, the Boost extension adds many many tags (77) ithout being similar to what already exists in DocBook, while mine tries to use fewer tags (18, 15 with a generic synopsisinfo) and to mimic the existing semantics. The final difference I see is that the Boost extension is really revolving around C++ (with concepts like headers, which are not present in that many languages), while I tried to be as language-agnostic as possible while being able to model as many things as possible. Just to highlight a few differences between both :). Actually, I had a look at BoostBook before choosing to design something else. I'm not going to argue on technical grounds for either side. However, I think it would be a big mistake to underestimate the importance of a community that is using a given technology, and thus is willing to help maintain it. BoostBuild is fully implemented and is part of the documentation toolchain used by many Boost components. Thus, when I mentored the project to migrate to DocBook 5 and eventually merge it into DocBook "mainstream", my hope was to enable the wider DocBook community to use it, making the tool and the project easier to maintain and evolve. This isn't a project to be taken on by a single person. Cordially, Stefan -- ...ich hab' noch einen Koffer in Berlin...
Re: [docbook] Re: [docbook-apps] proposed additions to DocBook for programming languages
Hi Stefan, The two tag sets serve a similar purpose, but are very different in their implementation: the Boost-based set looks like an equivalent to refentry & co. (the base item is an API/library), while the one I proposed on GitHub is rather based on the synopses (the base item is either a class, an enumeration, a macro, or a namespace — the closest item to Boost root). Also, the Boost extension adds many many tags (77) ithout being similar to what already exists in DocBook, while mine tries to use fewer tags (18, 15 with a generic synopsisinfo) and to mimic the existing semantics. The final difference I see is that the Boost extension is really revolving around C++ (with concepts like headers, which are not present in that many languages), while I tried to be as language-agnostic as possible while being able to model as many things as possible. Just to highlight a few differences between both :). Actually, I had a look at BoostBook before choosing to design something else. Thibaut Cuvelier On Mon, 29 Apr 2019 at 19:23, stefan wrote: > Hi Bob, > > I haven't used DocBook for quite a while, and unfortunately have been too > busy recently to keep track or even contribute. However, there are a number > of unfinished tasks that relate to this topic: > On 2019-04-29 12:41 p.m., Bob Stayton wrote: > > The DocBook Technical Committee has received a detailed proposal to > enhance the DocBook schema to better document the details of programming > languages. The Committee would like to request that those in the DocBook > community who use DocBook to document programming syntax to look over the > proposal and provide us with feedback. I'm sending this to both the > 'docbook' and 'docbook-apps' mailing lists to ensure coverage, so my > apologies for duplicate messages. > > They are proposing a number of new elements. Since DocBook already has a > large number of elements and since this markup is somewhat specialized, we > are considering making it an optional extension to the schema, similar to > the Publisher's extension. > > Quite a while ago A DocBook extension was developed as part of the Boost > project, adding support for C++ artefacts. While that work was based on > DocBook 4, I eventually mentored a GSoC student to port this to DocBook 5, > for eventual integration with both the DocBook 5 spec as well as stylesheet > support. And while the GSoC project was successfully completed, the branch > was never merged into master, and thus has never been formally released. > > I believe all the work is contained in the "API" branch of the XSLT 1.0 > repo: https://github.com/docbook/xslt10-stylesheets/tree/api. Notably, > the extension RelaxNG specs are in > https://github.com/docbook/xslt10-stylesheets/tree/api/docbook/relaxng/api/src, > and the stylesheet (which merely translate into the "core DocBook" > vocabulary) are in > https://github.com/docbook/xslt10-stylesheets/tree/api/xsl/api. > > It would be a shame if all of this work was wasted. > > > > You will note in the comment that the proposal will likely be modified to > use a generic synopsisinfo element instead of individually named synopsis > info elements as originally proposed. > > Here is a link to the proposal: > > https://github.com/docbook/docbook/issues/111 > > Your review and comments will help the DocBook TC in their deliberations > about this proposal. Thank you for your time. > > -- > Bob Stayton > Sagehill enterprisesb...@sagehill.net > > > [image: Stefan] > > -- > > ...ich hab' noch einen Koffer in Berlin... > > >
[docbook] Re: [docbook-apps] proposed additions to DocBook for programming languages
Hi Bob, I haven't used DocBook for quite a while, and unfortunately have been too busy recently to keep track or even contribute. However, there are a number of unfinished tasks that relate to this topic: On 2019-04-29 12:41 p.m., Bob Stayton wrote: The DocBook Technical Committee has received a detailed proposal to enhance the DocBook schema to better document the details of programming languages. The Committee would like to request that those in the DocBook community who use DocBook to document programming syntax to look over the proposal and provide us with feedback. I'm sending this to both the 'docbook' and 'docbook-apps' mailing lists to ensure coverage, so my apologies for duplicate messages. They are proposing a number of new elements. Since DocBook already has a large number of elements and since this markup is somewhat specialized, we are considering making it an optional extension to the schema, similar to the Publisher's extension. Quite a while ago A DocBook extension was developed as part of the Boost project, adding support for C++ artefacts. While that work was based on DocBook 4, I eventually mentored a GSoC student to port this to DocBook 5, for eventual integration with both the DocBook 5 spec as well as stylesheet support. And while the GSoC project was successfully completed, the branch was never merged into master, and thus has never been formally released. I believe all the work is contained in the "API" branch of the XSLT 1.0 repo: https://github.com/docbook/xslt10-stylesheets/tree/api. Notably, the extension RelaxNG specs are in https://github.com/docbook/xslt10-stylesheets/tree/api/docbook/relaxng/api/src, and the stylesheet (which merely translate into the "core DocBook" vocabulary) are in https://github.com/docbook/xslt10-stylesheets/tree/api/xsl/api. It would be a shame if all of this work was wasted. You will note in the comment that the proposal will likely be modified to use a generic synopsisinfo element instead of individually named synopsis info elements as originally proposed. Here is a link to the proposal: https://github.com/docbook/docbook/issues/111 Your review and comments will help the DocBook TC in their deliberations about this proposal. Thank you for your time. -- Bob Stayton Sagehill Enterprises b...@sagehill.net Stefan -- ...ich hab' noch einen Koffer in Berlin...
Re: [docbook-apps] proposed additions to DocBook for programming languages
Hi Bob, I haven't used DocBook for quite a while, and unfortunately have been too busy recently to keep track or even contribute. However, there are a number of unfinished tasks that relate to this topic: On 2019-04-29 12:41 p.m., Bob Stayton wrote: The DocBook Technical Committee has received a detailed proposal to enhance the DocBook schema to better document the details of programming languages. The Committee would like to request that those in the DocBook community who use DocBook to document programming syntax to look over the proposal and provide us with feedback. I'm sending this to both the 'docbook' and 'docbook-apps' mailing lists to ensure coverage, so my apologies for duplicate messages. They are proposing a number of new elements. Since DocBook already has a large number of elements and since this markup is somewhat specialized, we are considering making it an optional extension to the schema, similar to the Publisher's extension. Quite a while ago A DocBook extension was developed as part of the Boost project, adding support for C++ artefacts. While that work was based on DocBook 4, I eventually mentored a GSoC student to port this to DocBook 5, for eventual integration with both the DocBook 5 spec as well as stylesheet support. And while the GSoC project was successfully completed, the branch was never merged into master, and thus has never been formally released. I believe all the work is contained in the "API" branch of the XSLT 1.0 repo: https://github.com/docbook/xslt10-stylesheets/tree/api. Notably, the extension RelaxNG specs are in https://github.com/docbook/xslt10-stylesheets/tree/api/docbook/relaxng/api/src, and the stylesheet (which merely translate into the "core DocBook" vocabulary) are in https://github.com/docbook/xslt10-stylesheets/tree/api/xsl/api. It would be a shame if all of this work was wasted. You will note in the comment that the proposal will likely be modified to use a generic synopsisinfo element instead of individually named synopsis info elements as originally proposed. Here is a link to the proposal: https://github.com/docbook/docbook/issues/111 Your review and comments will help the DocBook TC in their deliberations about this proposal. Thank you for your time. -- Bob Stayton Sagehill Enterprises b...@sagehill.net Stefan -- ...ich hab' noch einen Koffer in Berlin...
[docbook] proposed additions to DocBook for programming languages
The DocBook Technical Committee has received a detailed proposal to enhance the DocBook schema to better document the details of programming languages. The Committee would like to request that those in the DocBook community who use DocBook to document programming syntax to look over the proposal and provide us with feedback. I'm sending this to both the 'docbook' and 'docbook-apps' mailing lists to ensure coverage, so my apologies for duplicate messages. They are proposing a number of new elements. Since DocBook already has a large number of elements and since this markup is somewhat specialized, we are considering making it an optional extension to the schema, similar to the Publisher's extension. You will note in the comment that the proposal will likely be modified to use a generic synopsisinfo element instead of individually named synopsis info elements as originally proposed. Here is a link to the proposal: https://github.com/docbook/docbook/issues/111 Your review and comments will help the DocBook TC in their deliberations about this proposal. Thank you for your time. -- Bob Stayton Sagehill Enterprises b...@sagehill.net
[docbook-apps] proposed additions to DocBook for programming languages
The DocBook Technical Committee has received a detailed proposal to enhance the DocBook schema to better document the details of programming languages. The Committee would like to request that those in the DocBook community who use DocBook to document programming syntax to look over the proposal and provide us with feedback. I'm sending this to both the 'docbook' and 'docbook-apps' mailing lists to ensure coverage, so my apologies for duplicate messages. They are proposing a number of new elements. Since DocBook already has a large number of elements and since this markup is somewhat specialized, we are considering making it an optional extension to the schema, similar to the Publisher's extension. You will note in the comment that the proposal will likely be modified to use a generic synopsisinfo element instead of individually named synopsis info elements as originally proposed. Here is a link to the proposal: https://github.com/docbook/docbook/issues/111 Your review and comments will help the DocBook TC in their deliberations about this proposal. Thank you for your time. -- Bob Stayton Sagehill Enterprises b...@sagehill.net
