Changing the website (Was: Need help with bootstrap.bat)

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
14 messages Options
Reply | Threaded
Open this post in threaded view
|

Changing the website (Was: Need help with bootstrap.bat)

Boost - Dev mailing list
2018-01-03 13:54 GMT+01:00 Daniel James via Boost <[hidden email]>:

> On 3 January 2018 at 10:04, Andrzej Krzemienski via Boost
> <[hidden email]> 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;

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Changing the website (Was: Need help with bootstrap.bat)

Boost - Dev mailing list
On 3 January 2018 at 13:27, Andrzej Krzemienski via Boost
<[hidden email]> 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?

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Changing the website (Was: Need help with bootstrap.bat)

Boost - Dev mailing list
2018-01-03 15:14 GMT+01:00 Daniel James via Boost <[hidden email]>:

> On 3 January 2018 at 13:27, Andrzej Krzemienski via Boost
> <[hidden email]> 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;

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Changing the website (Was: Need help with bootstrap.bat)

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 1/3/18 6:14 AM, Daniel James via Boost wrote:
 > On 3 January 2018 at 13:27, Andrzej Krzemienski via Boost
 > <[hidden email]> 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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Changing the website (Was: Need help with bootstrap.bat)

Boost - Dev mailing list
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
> > <[hidden email]> 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...
   


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Changing the website (Was: Need help with bootstrap.bat)

Boost - Dev mailing list
On 1/3/18 9:04 AM, Stefan Seefeld via Boost wrote:
> It's much easier and more pragmatic to
> look for incremental improvements.

Agreed - I should have added that to my list somewhere

Robert Ramey

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Changing the website (Was: Need help with bootstrap.bat)

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 3 January 2018 at 14:36, Andrzej Krzemienski via Boost
<[hidden email]> 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.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Changing the website (Was: Need help with bootstrap.bat)

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
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?


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Changing the website (Was: Need help with bootstrap.bat)

Boost - Dev mailing list
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...
   


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Changing the website (Was: Need help with bootstrap.bat)

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list

> On 3. Jan 2018, at 18:04, Stefan Seefeld via Boost <[hidden email]> 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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Changing the website (Was: Need help with bootstrap.bat)

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
2018-01-03 14:27 GMT+01:00 Andrzej Krzemienski <[hidden email]>:

>
> 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/guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros
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;

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Changing the website (Was: Need help with bootstrap.bat)

Boost - Dev mailing list
On 5 January 2018 at 15:27, Andrzej Krzemienski via Boost
<[hidden email]> 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/guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros
> 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.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Changing the website (Was: Need help with bootstrap.bat)

Boost - Dev mailing list
On 5 January 2018 at 15:44, Daniel James <[hidden email]> 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:
>
> https://svn.boost.org/trac10/wiki/BoostDocs/GettingStarted

I copied it to the new wiki:

https://github.com/boostorg/boost/wiki/Getting-Started-With-Documentation

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Changing the website (Was: Need help with bootstrap.bat)

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
AMDG

On 01/05/2018 08:44 AM, Daniel James via Boost wrote:
> On 5 January 2018 at 15:27, Andrzej Krzemienski via Boost
> <[hidden email]> 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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost