Re: [boost] [review] Review of Outcome v2 (Fri-19-Jan to Sun-28-Jan, 2018)

Subject: Re: [boost] [review] Review of Outcome v2 (Fri-19-Jan to Sun-28-Jan, 2018)
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2018-01-24 08:31:38

>> Most web browsers don't render modern static websites with AJAX,
>> accessibility, mobile rendering, semantic search etc from file:// for
>> security reasons. The problem is in the web browser, not in the site.
> 
> You could generate the static html using an appropriate offline theme.
> If accepted you'll in any event need either static html in doc/html, or
> a doc/Jamfile that builds said doc/html. Might as well do that now to
> give the reviewers an offline doc.

Here is an offline archive of the docs website as pulled and converted
by HTTrack:

https://github.com/ned14/outcome/releases/download/v2.0-boost-peer-review/outcome_html_docs_offline.zip

I had a quick flick through and it seems mostly the same. Search doesn't
work obviously. I would emphasise that the review submission is the
public website at https://ned14.github.io/outcome/, and not this zip
archive which hasn't received anything like the same amount of
validation and checking.

Regarding what else you said, yes one could simply run Hugo and tell it
to make an offline copy. After all the true source content is written in
Markdown, and actually any Markdown to HTML/PDF/DocBook processor will
technically do.

However the documentation took as long to do as everything else put
together (writing, testing, everything else). Some four months of effort
- and not just by me either - went into the docs alone. The public
website https://ned14.github.io/outcome/ has many problems and issues,
but at least I know what those are, and I am prepared for any review
feedback on those.

Quickly firing out an offline website, getting it properly validated and
throwing it into a ZIP file is not doable in the time available to me
before the review ends. I only get, at most, two free hours per day and
those go on writing emails like this one.

Regarding how these docs would end up in Boost if the library is
accepted, historically Boost has preferred to generate the docs from
their original sources rather than take a copy of the HTML dumped out. I
would assume this would continue to be the case, and so we'd need some
theme which outputs something with the Boost look and feel, and fix up
the Boost servers with Hugo et al and get them into a Jamfile as you say.

But those involve decisions by those who maintain the Boost website, and
many more weeks of tweaking things in whatever direction is chosen
ultimately. As I do not know what that decision would be until after
this review, I have kicked that can down the road for now. For all I
know, maybe they would prefer a static HTML dump, but I suspect not.

You're right Peter that all this is easy, but it is also time consuming
and detail orientated. And that means weeks of time must elapse as I am
currently on contract.

Also, nobody seems yet to have noticed the many problems in the
Standardese generated output. There is a fair bit of rope to pull in on
that yet too, Jonathan I am sure awaits feedback from this review with
anticipation.

Niall

-- 
ned Productions Limited Consulting
http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/