Subject: Re: [PATCH 0/5] Make PDF builds work again
To: Jonathan Corbet <corbet@lwn.net>, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org, Jim Davis <jim.epost@gmail.com>,
        Mauro Carvalho Chehab <mchehab@s-opensource.com>
References: <20170618234630.19964-1-corbet@lwn.net>
 <20170703082538.tskdygdzkxkcazcr@phenom.ffwll.local>
From: Frank Rowand <frowand.list@gmail.com>
Message-ID: <595D460B.2060105@gmail.com>
Date: Wed, 5 Jul 2017 13:03:23 -0700
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101
 Thunderbird/38.4.0
MIME-Version: 1.0
In-Reply-To: <20170703082538.tskdygdzkxkcazcr@phenom.ffwll.local>
Content-Type: text/plain; charset=windows-1252
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 2883
Lines: 63

On 07/03/17 01:25, Daniel Vetter wrote:
> On Sun, Jun 18, 2017 at 05:46:25PM -0600, Jonathan Corbet wrote:
>> I've just spent rather more time than I would like figuring out why the PDF
>> builds fail and what was needed to fix it.  The result is the following
>> patch series.  It's a combination of little mistakes and fragility in the
>> whole PDF build tool chain.
>>
>> Mauro, Daniel: Do you want the last two?  Or otherwise give me acks?  I'd
>> like to send the set Linusward forthwith so that 4.12 can come out with
>> a working PDF build.
> 
> Only now stumbled over the full thread, but the drm patch is already
> queued up for at least 4.13 (Dave was out and all that). I guess we could
> try to cherry-pick through stable.
> 
> Personally I don't care at all for PDF builds, the only thing we do in our
> autobuilder is html, same for me locally when building docs. That tends to
> keep working :-)
> 
> Also, 0-day only tests the htmlbuild. Maybe you want to ping Fu and ask
> him to add the pdfdocs to his build targets?
> -Daniel
> 
>>
>> In general, I'm dismayed by the fragility of the whole thing.  I'm also a
>> little concerned that nobody except Jim complained about the problem.
>> Perhaps nobody really cares about PDF output anymore?  In the absence of a
>> concerted effort on somebody's part, I predict that PDF building will be
>> broken much of the time.  I have to wonder if it's worth it...

I much prefer PDF output to html for my normal use. Not to get into a
debate about whether html or PDF is better, both have valuable use cases.
And it isn't PDF per se that I prefer - it could be any reasonable format
that contains the entire content in a single file, is easily scannable
("scrolled through", viewed by the human eye), easily searched, and can
be cut and pasted from.

As far as lack of complaints, I have been ignoring building documentation
until it feels to me like the issues from converting to the new system
have been worked out. And once that point is reached, then I need to
make time in my schedule to fix the in-source documentation so that
building the documents for device tree provides useful information
instead of incorrect information. If I was actively building
documentation I would have complained.


>> Jonathan Corbet (5):
>>   Docs: Include the Latex "ifthen" package
>>   Docs: Remove redundant geometry package inclusion
>>   Docs: fix table problems in ras.rst
>>   Docs: Use kernel-figure in vidioc-g-selection.rst
>>   DRM: Fix an incorrectly formatted table
>>
>>  Documentation/admin-guide/ras.rst                  | 10 ++--
>>  Documentation/conf.py                              |  3 +-
>>  .../media/uapi/v4l/vidioc-g-selection.rst          |  4 +-
>>  include/drm/bridge/dw_hdmi.h                       | 70 +++++++++++-----------
>>  4 files changed, 43 insertions(+), 44 deletions(-)
>>
>> -- 
>> 2.13.1
>>
>