Changing the website (Was: Need help with bootstrap.bat)
2018-01-03 13:54 GMT+01:00 Daniel James via Boost <boost@lists.boost.org>:
On 3 January 2018 at 10:04, Andrzej Krzemienski via Boost <boost@lists.boost.org> wrote:
(n.b. It was very difficult to find this page as there is no direct link from www.boost.org).
I'll add a link to the 'getting started' section. Maybe we should move more content onto the github wiki? It's just a git repo with markdown pages so it shouldn't be too hard to serve it from the website if people would like it to be more integrated.
Let me share with you my recent experience. I was looking for something like "getting started for Boost developers" and could not find a place.In the front page there is section "INTRODUCTION", but it looks like content for potential users (rather than developers). There is section "DEVELOPMENT" but the content is more like "how to submit a new library", but no "getting started with developement" (on somebody else's library) There is a "WELCOME" -> "Getting started", but it looks like one for the users. (it recommends downloading a zip file). There is this non-obvious path: DEVELOPEMENT -> Reporting and Fixing Bugs. While there, click on "git repositories". It opens a stub page that says it has been superseded by another, and when you push on a link you get there. But this really should be simpler. Maybe in the front page we should have "DEVELOPMENT" -> "Getting Started" that links directly to https://github.com/boostorg/boost/wiki/Getting-Started Or maybe the topics should be divided differently: - Getting started with using Boost Libraries - Getting started with applying improvements to existing Libraries - Getting started with submitting a new library. I consider this more important than where actually the content is hosted. Regards, &rzej;
On 3 January 2018 at 13:27, Andrzej Krzemienski via Boost <boost@lists.boost.org> wrote:
I consider this more important than where actually the content is hosted.
Sure, but from my perspective the problem is that no one is maintaining a lot of these pages. If there's a simple way to make it easier for other people to do it, then I'd like to explore that. Making proposals to reorganize the website is nice, but is anyone going to do it?
2018-01-03 15:14 GMT+01:00 Daniel James via Boost <boost@lists.boost.org>:
On 3 January 2018 at 13:27, Andrzej Krzemienski via Boost <boost@lists.boost.org> wrote:
I consider this more important than where actually the content is hosted.
Sure, but from my perspective the problem is that no one is maintaining a lot of these pages. If there's a simple way to make it easier for other people to do it, then I'd like to explore that.
You mean, make this GitHub Wiki more popular and encourage people to update/maintain it? Sure, this sounds good. Making proposals to reorganize the website is nice, but is anyone
going to do it?
My proposal is to add a link in that menu, or move one or two links around. I think we have access to sources under GitHub? I can do it if I am given access. Regards, &rzej;
On 3 January 2018 at 14:36, Andrzej Krzemienski via Boost <boost@lists.boost.org> wrote:
Making proposals to reorganize the website is nice, but is anyone
going to do it?
My proposal is to add a link in that menu, or move one or two links around. I think we have access to sources under GitHub? I can do it if I am given access.
The sidebar menu is at: https://github.com/boostorg/website/tree/master/common 'sidebar-*.html' contains the sidebars for various parts of the site, 'sidebar-boost.html' is the home page sidebar. This uses virtual includes to import the menus from the 'menu-*.html' files. The section menus are included in every page, CSS is used to only display the menu for the current section. You can create pull requests, or I could add you to the website team, and you could try changing the beta branch.
On 1/3/18 6:14 AM, Daniel James via Boost wrote:
On 3 January 2018 at 13:27, Andrzej Krzemienski via Boost <boost@lists.boost.org> wrote:
I consider this more important than where actually the content is
hosted.
Sure, but from my perspective the problem is that no one is maintaining a lot of these pages. If there's a simple way to make it easier for other people to do it, then I'd like to explore that. Making proposals to reorganize the website is nice, but is anyone going to do it? The whole website thing is ripe for some really great idea. We need some new ideas/approaches here.
a) It has to be composed of simpler more orthogonal parts b) Each of which can be easily and sort of maintained by a large number of individuals who have responsabiity for their own parts c) It has to be easy to do d) Use simple tools which are going to be around for a while e) Create a shared UI/css, etc so that understanding one part means that a user understands the other parts, etc. f) It has to address security issues g) It would be nice to have the ability for users to add information to web pages - corrections etc. Maybe git hub issues would work for this. I don't know anything which really encompasses all of the above, but there are somethings which have good/helpful models for some aspects of the above. cppreference has a good model for shared look and feel across widely varying types of content - language, libraries, etc. It is also updatable by members. Something built on this would also be able to incorporate library independently created documentation with a common look and feel. The guy who created this gave a great talk at CppCon a couple of years ago. Maybe we need to invite him to C++Now (BoostCon?) to get some ideas. Of course github has worked out well ideal for managing content for such a thing. I'm skeptical of things like php, or ... the flavor of the month web design tool. Anything that tries to do too much seems to lead into a cul-de-sac. Some of these ideas I've tried to prototype in the incubator with limited success. To summarize, this is a huge topic. I'm sort of skeptical that we have the resources (of varied kinds) to actually do it. But if one's reach is not beyond his grasp - what's a heaven for? (apologies to Robert Burns) Robert Ramey
On 03.01.2018 11:47, Robert Ramey via Boost wrote:
On 1/3/18 6:14 AM, Daniel James via Boost wrote:
On 3 January 2018 at 13:27, Andrzej Krzemienski via Boost <boost@lists.boost.org> wrote:
I consider this more important than where actually the content is
hosted.
Sure, but from my perspective the problem is that no one is maintaining a lot of these pages. If there's a simple way to make it easier for other people to do it, then I'd like to explore that. Making proposals to reorganize the website is nice, but is anyone going to do it? The whole website thing is ripe for some really great idea. We need some new ideas/approaches here.
a) It has to be composed of simpler more orthogonal parts b) Each of which can be easily and sort of maintained by a large number of individuals who have responsabiity for their own parts c) It has to be easy to do d) Use simple tools which are going to be around for a while e) Create a shared UI/css, etc so that understanding one part means that a user understands the other parts, etc. f) It has to address security issues g) It would be nice to have the ability for users to add information to web pages - corrections etc. Maybe git hub issues would work for this.
I don't know anything which really encompasses all of the above, but there are somethings which have good/helpful models for some aspects of the above.
If we always seek to remodel everything at once we make life unnecessarily hard for ourselves. It's much easier and more pragmatic to look for incremental improvements. And it brings me back to my favourite topic: modularity. github already allows per-project pages, and some of the github projects use them (e.g. http://boostorg.github.io/python/). So let's assume for a moment that all Boost projects use github pages to publish their documentation. The remainder of `www.boost.org` could then be migrated to github pages, too, mostly consisting of references to the project-specific pages. I think such a scenario meets most of your items above: it's modular ("composed of orthogonal parts"), more easily maintained (each by their project's maintainers). (I'd leave out the discussion about tools etc., as I think that's entirely up to the projects.) But, as usual, some people will insist that such modularization is bad, so it's an all-or-nothing thing, and in the end, nothing will change. However, if there was motivation to try out something like the above, I'd be more than happy to help. Stefan -- ...ich hab' noch einen Koffer in Berlin...
Stefan Seefeld wrote:
github already allows per-project pages, and some of the github projects use them (e.g. http://boostorg.github.io/python/). So let's assume for a moment that all Boost projects use github pages to publish their documentation.
Doesn't this ignore the current release procedure, which builds the html documentation from the qbk/rst/asciidoc sources in the repositories and includes the generated result into the release?
On 03.01.2018 13:29, Peter Dimov via Boost wrote:
Stefan Seefeld wrote:
github already allows per-project pages, and some of the github projects use them (e.g. http://boostorg.github.io/python/). So let's assume for a moment that all Boost projects use github pages to publish their documentation.
Doesn't this ignore the current release procedure, which builds the html documentation from the qbk/rst/asciidoc sources in the repositories and includes the generated result into the release?
I don't see any conflict there. In case of Boost.Python, it's the exact same content / build process used for both, which is why I believe this would be an almost trivial change for other projects, too. Stefan -- ...ich hab' noch einen Koffer in Berlin...
On 3. Jan 2018, at 18:04, Stefan Seefeld via Boost <boost@lists.boost.org> wrote:
If we always seek to remodel everything at once we make life unnecessarily hard for ourselves. It's much easier and more pragmatic to look for incremental improvements. And it brings me back to my favourite topic: modularity. github already allows per-project pages, and some of the github projects use them (e.g. http://boostorg.github.io/python/ <http://boostorg.github.io/python/>). So let's assume for a moment that all Boost projects use github pages to publish their documentation. The remainder of `www.boost.org <http://www.boost.org/>` could then be migrated to github pages, too, mostly consisting of references to the project-specific pages.
I think such a scenario meets most of your items above: it's modular ("composed of orthogonal parts"), more easily maintained (each by their project's maintainers). (I'd leave out the discussion about tools etc., as I think that's entirely up to the projects.)
I think that's a great proposal. I also hope that Andrzej gets access to do what he suggested. I stumbled over the same thing. Just my 2 cents, Hans
2018-01-03 14:27 GMT+01:00 Andrzej Krzemienski <akrzemi1@gmail.com>:
Let me share with you my recent experience. I was looking for something like "getting started for Boost developers" and could not find a place.In the front page there is section "INTRODUCTION", but it looks like content for potential users (rather than developers). There is section "DEVELOPMENT" but the content is more like "how to submit a new library", but no "getting started with developement" (on somebody else's library) There is a "WELCOME" -> "Getting started", but it looks like one for the users. (it recommends downloading a zip file).
There is this non-obvious path: DEVELOPEMENT -> Reporting and Fixing Bugs. While there, click on "git repositories". It opens a stub page that says it has been superseded by another, and when you push on a link you get there. But this really should be simpler.
Maybe in the front page we should have "DEVELOPMENT" -> "Getting Started" that links directly to https://github.com/boostorg/ boost/wiki/Getting-Started
Or maybe the topics should be divided differently:
- Getting started with using Boost Libraries - Getting started with applying improvements to existing Libraries - Getting started with submitting a new library.
I consider this more important than where actually the content is hosted.
In the same spirit, I am missing instructions on how to build documentation for the libraries. This bootstrapping gives the impression that the boost package is self-contained. But when I try to build docs from any library using Quickbook, say type_erasure, I am getting errors from b2: ``` error: xsltproc: Could not run "xsltproc" -V. 'xsltproc' is not recognized as an internal or external command, operable program or batch file. ``` Apparently, having `xsltproc` is a prerequisite, but it is not mentioned in the "Getting Started" wiki: https://github.com/boostorg/boost/wiki/Getting-Started Is there a place where I can find prerequisites like this one? (and document them on Wiki). Another one. I am not sure if it is related to Boost.Config, or generally to "Boost basics" I was trying to add another macro to Boost.Config. I followed the instructions at http://www.boost.org/doc/libs/1_66_0/libs/config/doc/html/boost_config/guide... One thing it says is "Document the macro in this documentation (please do not forget this step!!)" Because the doc folder contains both QBK and HTML files, I assume that I should modify the QBK files, run b2, and the corresponding HTML files will get updated. But when I run b2, I get message Performing configuration checks
- 32-bit : no (cached) - 64-bit : yes (cached) - arm : no (cached) - mips1 : no (cached) - power : no (cached) - sparc : no (cached) - x86 : yes (cached) - symlinks supported : no (cached) - junctions supported : yes (cached) - hardlinks supported : yes (cached) WARNING: Unable to construct ./standalone of type BOOSTBOOK with these properties: <abi>ms <address-model>64 <architecture>x86 <asynch-exceptions>off <binary-format>pe <conditional>@Jamfile<C:\_source\boost>%Jamfile<C:\_source\boost>.handle-static-runtime <conditional>@Jamfile<C:\_source\boost>%boostcpp.deduce-address-model <conditional>@Jamfile<C:\_source\boost>%boostcpp.deduce-architecture <conditional>@Jamfile<C:\_source\boost>%threadapi-feature.detect <context-impl>fcontext <context-switch>cc <debug-symbols>on <deduced-address-model>64 <deduced-architecture>x86 <define>BOOST_ALL_NO_LIB=1 <exception-handling>on <extern-c-nothrow>off <format>html <hardcode-dll-paths>true <host-os>windows <implicit-dependency>object(notfile-target)@3287 <include>../../.. <inlining>off <install-dependencies>off <link>shared <optimization>off <os>NT <pch>on <preserve-test-targets>on <profiling>off <python-debugging>off <rtti>on <runtime-debugging>on <runtime-link>shared <stdlib>native <strip>off <suppress-import-lib>false <symlink-location>project-relative <tag>@Jamfile<C:\_source\boost>%Jamfile<C:\_source\boost>.tag <target-os>windows <testing.execute>on <threadapi>win32 <threading>single <toolset-gcc:flavor>mingw <toolset-gcc:linker-type>gnu <toolset-gcc:version>7.2.0 <toolset>gcc <user-interface>console <variant>debug <vectorize>off <warnings-as-errors>off <warnings>on <xsl:param>admon.graphics=1 <xsl:param>boost.defaults=Boost <xsl:param>boost.root=../../../.. <xsl:param>chunk.section.depth=1 <xsl:param>toc.max.depth=2 <xsl:param>toc.section.depth=2 WARNING: Considered these as possible generators: WARNING: quickbook.quickbook-to-boostbook with source types { QUICKBOOK } and requirements { } ...patience... ...patience... ...found 3644 targets...
And the HTML content is not updated. Maybe I am missing something obvious that every Boost developer knows? Any help would be appreciated. Regards, &rzej;
On 5 January 2018 at 15:27, Andrzej Krzemienski via Boost <boost@lists.boost.org> wrote:
``` error: xsltproc: Could not run "xsltproc" -V. 'xsltproc' is not recognized as an internal or external command, operable program or batch file. ``` Apparently, having `xsltproc` is a prerequisite, but it is not mentioned in the "Getting Started" wiki: https://github.com/boostorg/boost/wiki/Getting-Started
Is there a place where I can find prerequisites like this one? (and document them on Wiki).
There's a page on the old wiki: https://svn.boost.org/trac10/wiki/BoostDocs/GettingStarted
Another one. I am not sure if it is related to Boost.Config, or generally to "Boost basics" I was trying to add another macro to Boost.Config. I followed the instructions at http://www.boost.org/doc/libs/1_66_0/libs/config/doc/html/boost_config/guide... One thing it says is "Document the macro in this documentation (please do not forget this step!!)" Because the doc folder contains both QBK and HTML files, I assume that I should modify the QBK files, run b2, and the corresponding HTML files will get updated. But when I run b2, I get message
[snip]
WARNING: Unable to construct ./standalone of type BOOSTBOOK with these
I think this means that quickbook isn't configured. If you add a 'using quickbook ;' to your user-config.jam it should work.
On 5 January 2018 at 15:44, Daniel James <dnljms@gmail.com> wrote:
On 5 January 2018 at 15:27, Andrzej Krzemienski via Boost
Is there a place where I can find prerequisites like this one? (and document them on Wiki).
There's a page on the old wiki:
I copied it to the new wiki: https://github.com/boostorg/boost/wiki/Getting-Started-With-Documentation
AMDG On 01/05/2018 08:44 AM, Daniel James via Boost wrote:
On 5 January 2018 at 15:27, Andrzej Krzemienski via Boost <boost@lists.boost.org> wrote:
WARNING: Unable to construct ./standalone of type BOOSTBOOK with these
I think this means that quickbook isn't configured. If you add a 'using quickbook ;' to your user-config.jam it should work.
In general, all documentation Jamfiles are supposed to do this automatically. (Unfortunately, many documentation Jamfiles were written before it was properly supported, and were never updated.) In Christ, Steven Watanabe
participants (7)
-
Andrzej Krzemienski -
Daniel James -
Hans Dembinski -
Peter Dimov -
Robert Ramey -
Stefan Seefeld -
Steven Watanabe