Re: [Boost-docs] GitHub no longer renders html

Subject: Re: [Boost-docs] GitHub no longer renders html
From: Stefan Seefeld (stefan_at_[hidden])
Date: 2016-10-07 11:41:16

On 07.10.2016 05:13, Paul A. Bristow wrote:
>> I'm not sure about "the Right Thing", as I never build anything "in
>> tree". In fact, I believe that building a stand-alone documentation tree
>> is very useful for example because it allows to be packaged and
>> installed separately.
> I conclude that the nub of the problem with the docs as built is that there are very many links to code, for example, "The C++ code
> is at ... " links, and that means you need to know where the file will be.  When the thing is in the final Boost tree structure,
> that works fine, but during development and review, these files are in ones GitHub repos.

It all depends on who your target audience is. It sounds like you expect
the audience to be those who have the whole Boost tree in front of them.

I would never assume that. I wouldn't even assume readers of my docs to
have my project's sources. In fact, many platforms provide a
Boost.Python to be installed as binary, so developers may find it in
standard locations. Still, they need to have access to documentation.
If I had to refer to source code by links, I would link to the repo
itself, not some location I cloned the sources into.

> I've played with GitHub pages, pushing just the /html but that doesn't give these links. Perhaps I need to copy the whole repos ?

While that may work (gh-pages is just another branch, which by default
contains the sources, unless you remove them), it has its own limit. For
example, if the user wants to navigate from the docs to the sources and
from there inspect the code history...

> However, the combination of PDF version for the quick reviewers, and to clone the whole repos to the readers machine seems a
> satisfactory compromise.

> Thanks.
>
> Paul

        Stefan

-- 
      ...ich hab' noch einen Koffer in Berlin...