You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@couchdb.apache.org by Joan Touzet <wo...@apache.org> on 2017/03/18 04:55:43 UTC
[PROPOSAL] Drop PDF / texinfo documentation builds
Hi everyone,
I'd like to propose dropping the PDF and texinfo targets from our
documentation build, or at the very least, having them not be part of
the default target / not standard deliverables for the project.
We'd continue to build HTML documentation as part of the workflow,
naturally, as well as the man pages.
I don't have any solid numbers, but I'm fairly sure most people use
https://docs.couchdb.org/ or a locally installed copy for their
documentation for CouchDB rather than the PDF documentation. I
personally can't remember the last time I opened the docs in PDF form. I
also have never seen anyone refer to the PDF docs on the mailing lists,
IRC or Slack when asking for advice or support.
I've also never seen anyone use or talk about the texinfo target, and
I've not used them myself.
Dropping this dependency will allow us to drop TeX/LaTeX from our build
chain, which speeds up build times by about 90 seconds and reduces the
size of containers currently being built for our Jenkins CI workflow.
It also means CouchDB devs don't have to install 0.5-1.5GB worth of
toolset.
I've captured this in JIRA as
https://issues.apache.org/jira/browse/COUCHDB-3329 and have PRs ready
to fire off if people agree.
Your thoughts?
-Joan
Re: [PROPOSAL] Drop PDF / texinfo documentation builds
Posted by Garren Smith <ga...@apache.org>.
+1
On Sat, 18 Mar 2017 at 1:18 PM Dave Cottlehuber <dc...@skunkwerks.at> wrote:
> On Sat, 18 Mar 2017, at 05:55, Joan Touzet wrote:
> > Hi everyone,
> >
> > I'd like to propose dropping the PDF and texinfo targets from our
>
> +1 send them to the dumpster its long overdue.
>
> A+
> Dave
>
Re: [PROPOSAL] Drop PDF / texinfo documentation builds
Posted by Dave Cottlehuber <dc...@skunkwerks.at>.
On Sat, 18 Mar 2017, at 05:55, Joan Touzet wrote:
> Hi everyone,
>
> I'd like to propose dropping the PDF and texinfo targets from our
+1 send them to the dumpster its long overdue.
A+
Dave
Re: [PROPOSAL] Drop PDF / texinfo documentation builds
Posted by Joan Touzet <wo...@apache.org>.
Thanks everyone. I figured there would be universal agreement.
PRs are live.
-Joan
----- Original Message -----
> From: "Robert Newson" <rn...@apache.org>
> To: dev@couchdb.apache.org
> Sent: Saturday, March 18, 2017 4:10:31 PM
> Subject: Re: [PROPOSAL] Drop PDF / texinfo documentation builds
>
> +1. Please use fire.
>
> > On 18 Mar 2017, at 17:44, Robert Kowalski <ro...@kowalski.gd> wrote:
> >
> > good idea, +1
> >
> >> On Sat, Mar 18, 2017 at 9:14 AM, Jan Lehnardt <ma...@jan.io> wrote:
> >>
> >> +1
> >>
> >> Cheers
> >> Jan
> >> --
> >>
> >>> On 18 Mar 2017, at 05:55, Joan Touzet <wo...@apache.org> wrote:
> >>>
> >>> Hi everyone,
> >>>
> >>> I'd like to propose dropping the PDF and texinfo targets from our
> >>> documentation build, or at the very least, having them not be
> >>> part of
> >>> the default target / not standard deliverables for the project.
> >>>
> >>> We'd continue to build HTML documentation as part of the
> >>> workflow,
> >>> naturally, as well as the man pages.
> >>>
> >>> I don't have any solid numbers, but I'm fairly sure most people
> >>> use
> >>> https://docs.couchdb.org/ or a locally installed copy for their
> >>> documentation for CouchDB rather than the PDF documentation. I
> >>> personally can't remember the last time I opened the docs in PDF
> >>> form. I
> >>> also have never seen anyone refer to the PDF docs on the mailing
> >>> lists,
> >>> IRC or Slack when asking for advice or support.
> >>>
> >>> I've also never seen anyone use or talk about the texinfo target,
> >>> and
> >>> I've not used them myself.
> >>>
> >>> Dropping this dependency will allow us to drop TeX/LaTeX from our
> >>> build
> >>> chain, which speeds up build times by about 90 seconds and
> >>> reduces the
> >>> size of containers currently being built for our Jenkins CI
> >>> workflow.
> >>> It also means CouchDB devs don't have to install 0.5-1.5GB worth
> >>> of
> >>> toolset.
> >>>
> >>> I've captured this in JIRA as
> >>> https://issues.apache.org/jira/browse/COUCHDB-3329 and have PRs
> >>> ready
> >>> to fire off if people agree.
> >>>
> >>> Your thoughts?
> >>>
> >>> -Joan
> >>
>
Re: [PROPOSAL] Drop PDF / texinfo documentation builds
Posted by Robert Newson <rn...@apache.org>.
+1. Please use fire.
> On 18 Mar 2017, at 17:44, Robert Kowalski <ro...@kowalski.gd> wrote:
>
> good idea, +1
>
>> On Sat, Mar 18, 2017 at 9:14 AM, Jan Lehnardt <ma...@jan.io> wrote:
>>
>> +1
>>
>> Cheers
>> Jan
>> --
>>
>>> On 18 Mar 2017, at 05:55, Joan Touzet <wo...@apache.org> wrote:
>>>
>>> Hi everyone,
>>>
>>> I'd like to propose dropping the PDF and texinfo targets from our
>>> documentation build, or at the very least, having them not be part of
>>> the default target / not standard deliverables for the project.
>>>
>>> We'd continue to build HTML documentation as part of the workflow,
>>> naturally, as well as the man pages.
>>>
>>> I don't have any solid numbers, but I'm fairly sure most people use
>>> https://docs.couchdb.org/ or a locally installed copy for their
>>> documentation for CouchDB rather than the PDF documentation. I
>>> personally can't remember the last time I opened the docs in PDF form. I
>>> also have never seen anyone refer to the PDF docs on the mailing lists,
>>> IRC or Slack when asking for advice or support.
>>>
>>> I've also never seen anyone use or talk about the texinfo target, and
>>> I've not used them myself.
>>>
>>> Dropping this dependency will allow us to drop TeX/LaTeX from our build
>>> chain, which speeds up build times by about 90 seconds and reduces the
>>> size of containers currently being built for our Jenkins CI workflow.
>>> It also means CouchDB devs don't have to install 0.5-1.5GB worth of
>>> toolset.
>>>
>>> I've captured this in JIRA as
>>> https://issues.apache.org/jira/browse/COUCHDB-3329 and have PRs ready
>>> to fire off if people agree.
>>>
>>> Your thoughts?
>>>
>>> -Joan
>>
Re: [PROPOSAL] Drop PDF / texinfo documentation builds
Posted by Robert Kowalski <ro...@kowalski.gd>.
good idea, +1
On Sat, Mar 18, 2017 at 9:14 AM, Jan Lehnardt <ma...@jan.io> wrote:
> +1
>
> Cheers
> Jan
> --
>
> > On 18 Mar 2017, at 05:55, Joan Touzet <wo...@apache.org> wrote:
> >
> > Hi everyone,
> >
> > I'd like to propose dropping the PDF and texinfo targets from our
> > documentation build, or at the very least, having them not be part of
> > the default target / not standard deliverables for the project.
> >
> > We'd continue to build HTML documentation as part of the workflow,
> > naturally, as well as the man pages.
> >
> > I don't have any solid numbers, but I'm fairly sure most people use
> > https://docs.couchdb.org/ or a locally installed copy for their
> > documentation for CouchDB rather than the PDF documentation. I
> > personally can't remember the last time I opened the docs in PDF form. I
> > also have never seen anyone refer to the PDF docs on the mailing lists,
> > IRC or Slack when asking for advice or support.
> >
> > I've also never seen anyone use or talk about the texinfo target, and
> > I've not used them myself.
> >
> > Dropping this dependency will allow us to drop TeX/LaTeX from our build
> > chain, which speeds up build times by about 90 seconds and reduces the
> > size of containers currently being built for our Jenkins CI workflow.
> > It also means CouchDB devs don't have to install 0.5-1.5GB worth of
> > toolset.
> >
> > I've captured this in JIRA as
> > https://issues.apache.org/jira/browse/COUCHDB-3329 and have PRs ready
> > to fire off if people agree.
> >
> > Your thoughts?
> >
> > -Joan
>
Re: [PROPOSAL] Drop PDF / texinfo documentation builds
Posted by Jan Lehnardt <ma...@jan.io>.
+1
Cheers
Jan
--
> On 18 Mar 2017, at 05:55, Joan Touzet <wo...@apache.org> wrote:
>
> Hi everyone,
>
> I'd like to propose dropping the PDF and texinfo targets from our
> documentation build, or at the very least, having them not be part of
> the default target / not standard deliverables for the project.
>
> We'd continue to build HTML documentation as part of the workflow,
> naturally, as well as the man pages.
>
> I don't have any solid numbers, but I'm fairly sure most people use
> https://docs.couchdb.org/ or a locally installed copy for their
> documentation for CouchDB rather than the PDF documentation. I
> personally can't remember the last time I opened the docs in PDF form. I
> also have never seen anyone refer to the PDF docs on the mailing lists,
> IRC or Slack when asking for advice or support.
>
> I've also never seen anyone use or talk about the texinfo target, and
> I've not used them myself.
>
> Dropping this dependency will allow us to drop TeX/LaTeX from our build
> chain, which speeds up build times by about 90 seconds and reduces the
> size of containers currently being built for our Jenkins CI workflow.
> It also means CouchDB devs don't have to install 0.5-1.5GB worth of
> toolset.
>
> I've captured this in JIRA as
> https://issues.apache.org/jira/browse/COUCHDB-3329 and have PRs ready
> to fire off if people agree.
>
> Your thoughts?
>
> -Joan
Re: [PROPOSAL] Drop PDF / texinfo documentation builds
Posted by Joan Touzet <wo...@apache.org>.
Hi Katharina,
No, that is not the case. readthedocs.org (which hosts docs.couchdb.org
for us) still auto-builds PDF and EPUB documentation. You'll still
have access to that for as long as readthedocs.org sticks around (and
as long as we continue to use them to host our online docs, which is
for the foreseeable future). No worries!
This just means that PDF (and EPUB, incidentally) is not automatically
built as part of our /internal/ release process -- and not built
automatically as part of our /testing/ procedure.
If you're downloading the CouchDB documentaiton from source, you can
still build PDFs by running
make pdf
though it sounds like you're not working with our source directly.
And yes, we're trying to increase the velocity of our project ;)
Best,
Joan
----- Original Message -----
> From: "Katharina Hößel" <k....@mailbox.org>
> To: dev@couchdb.apache.org
> Sent: Tuesday, March 21, 2017 5:26:08 PM
> Subject: Re: [PROPOSAL] Drop PDF / texinfo documentation builds
>
> Wow, that change happened more quickly than I expected. I assume this
> means that there will be no PDF file available for download - just
> HTML
> and EPUB?
>
> If that's the case, there is one downside I'm seeing: The PDF is
> currently the only way to properly quote the CouchDB docs in
> scientific
> work.
>
> When I'm writing a thesis/paper/etc, refering to the large PDF file
> with page numbers is a more feasible option than refering to
> docs.couchdb.org - because you have to add a single bibliography
> entry
> for every unique URL you are citing.
> With a PDF, just add one single bib entry, and then cite pages.
> Having
> a canonical version of the document (such as [1]) makes sure every
> reviewer sees the same version of your document. Perfect.
>
> Apart from that, even in 2017, I feel that PDF files still have major
> advantages regarding offline usage, portability and printability that
> HTML and EPUB cannot offer (yet).
>
> I'd also be interested if there are any solid numbers to compare
> downloads of different formats of the docs via [2].
>
> [1] https://media.readthedocs.org/pdf/couchdb/latest/couchdb.pdf
> [2] http://docs.couchdb.org/en/2.0.0/download.html
>
>
>
> Am Sat, 18 Mar 2017 00:55:43 -0400 (EDT)
> schrieb Joan Touzet <wo...@apache.org>:
>
> > Hi everyone,
> >
> > I'd like to propose dropping the PDF and texinfo targets from our
> > documentation build, or at the very least, having them not be part
> > of
> > the default target / not standard deliverables for the project.
> >
> > We'd continue to build HTML documentation as part of the workflow,
> > naturally, as well as the man pages.
> >
> > I don't have any solid numbers, but I'm fairly sure most people use
> > https://docs.couchdb.org/ or a locally installed copy for their
> > documentation for CouchDB rather than the PDF documentation. I
> > personally can't remember the last time I opened the docs in PDF
> > form. I also have never seen anyone refer to the PDF docs on the
> > mailing lists, IRC or Slack when asking for advice or support.
> >
> > I've also never seen anyone use or talk about the texinfo target,
> > and
> > I've not used them myself.
> >
> > Dropping this dependency will allow us to drop TeX/LaTeX from our
> > build chain, which speeds up build times by about 90 seconds and
> > reduces the size of containers currently being built for our
> > Jenkins
> > CI workflow. It also means CouchDB devs don't have to install
> > 0.5-1.5GB worth of toolset.
> >
> > I've captured this in JIRA as
> > https://issues.apache.org/jira/browse/COUCHDB-3329 and have PRs
> > ready
> > to fire off if people agree.
> >
> > Your thoughts?
> >
> > -Joan
>
Re: [PROPOSAL] Drop PDF / texinfo documentation builds
Posted by Katharina Hößel <k....@mailbox.org>.
Wow, that change happened more quickly than I expected. I assume this
means that there will be no PDF file available for download - just HTML
and EPUB?
If that's the case, there is one downside I'm seeing: The PDF is
currently the only way to properly quote the CouchDB docs in scientific
work.
When I'm writing a thesis/paper/etc, refering to the large PDF file
with page numbers is a more feasible option than refering to
docs.couchdb.org - because you have to add a single bibliography entry
for every unique URL you are citing.
With a PDF, just add one single bib entry, and then cite pages. Having
a canonical version of the document (such as [1]) makes sure every
reviewer sees the same version of your document. Perfect.
Apart from that, even in 2017, I feel that PDF files still have major
advantages regarding offline usage, portability and printability that
HTML and EPUB cannot offer (yet).
I'd also be interested if there are any solid numbers to compare
downloads of different formats of the docs via [2].
[1] https://media.readthedocs.org/pdf/couchdb/latest/couchdb.pdf
[2] http://docs.couchdb.org/en/2.0.0/download.html
Am Sat, 18 Mar 2017 00:55:43 -0400 (EDT)
schrieb Joan Touzet <wo...@apache.org>:
> Hi everyone,
>
> I'd like to propose dropping the PDF and texinfo targets from our
> documentation build, or at the very least, having them not be part of
> the default target / not standard deliverables for the project.
>
> We'd continue to build HTML documentation as part of the workflow,
> naturally, as well as the man pages.
>
> I don't have any solid numbers, but I'm fairly sure most people use
> https://docs.couchdb.org/ or a locally installed copy for their
> documentation for CouchDB rather than the PDF documentation. I
> personally can't remember the last time I opened the docs in PDF
> form. I also have never seen anyone refer to the PDF docs on the
> mailing lists, IRC or Slack when asking for advice or support.
>
> I've also never seen anyone use or talk about the texinfo target, and
> I've not used them myself.
>
> Dropping this dependency will allow us to drop TeX/LaTeX from our
> build chain, which speeds up build times by about 90 seconds and
> reduces the size of containers currently being built for our Jenkins
> CI workflow. It also means CouchDB devs don't have to install
> 0.5-1.5GB worth of toolset.
>
> I've captured this in JIRA as
> https://issues.apache.org/jira/browse/COUCHDB-3329 and have PRs ready
> to fire off if people agree.
>
> Your thoughts?
>
> -Joan
Re: [PROPOSAL] Drop PDF / texinfo documentation builds
Posted by Paul Davis <pa...@gmail.com>.
+1
On Sat, Mar 18, 2017 at 8:15 AM Nick Vatamaniuc <va...@gmail.com> wrote:
> +1
>
> On Mar 18, 2017 12:56 AM, "Joan Touzet" <wo...@apache.org> wrote:
>
> > Hi everyone,
> >
> > I'd like to propose dropping the PDF and texinfo targets from our
> > documentation build, or at the very least, having them not be part of
> > the default target / not standard deliverables for the project.
> >
> > We'd continue to build HTML documentation as part of the workflow,
> > naturally, as well as the man pages.
> >
> > I don't have any solid numbers, but I'm fairly sure most people use
> > https://docs.couchdb.org/ or a locally installed copy for their
> > documentation for CouchDB rather than the PDF documentation. I
> > personally can't remember the last time I opened the docs in PDF form. I
> > also have never seen anyone refer to the PDF docs on the mailing lists,
> > IRC or Slack when asking for advice or support.
> >
> > I've also never seen anyone use or talk about the texinfo target, and
> > I've not used them myself.
> >
> > Dropping this dependency will allow us to drop TeX/LaTeX from our build
> > chain, which speeds up build times by about 90 seconds and reduces the
> > size of containers currently being built for our Jenkins CI workflow.
> > It also means CouchDB devs don't have to install 0.5-1.5GB worth of
> > toolset.
> >
> > I've captured this in JIRA as
> > https://issues.apache.org/jira/browse/COUCHDB-3329 and have PRs ready
> > to fire off if people agree.
> >
> > Your thoughts?
> >
> > -Joan
> >
>
Re: [PROPOSAL] Drop PDF / texinfo documentation builds
Posted by Nick Vatamaniuc <va...@gmail.com>.
+1
On Mar 18, 2017 12:56 AM, "Joan Touzet" <wo...@apache.org> wrote:
> Hi everyone,
>
> I'd like to propose dropping the PDF and texinfo targets from our
> documentation build, or at the very least, having them not be part of
> the default target / not standard deliverables for the project.
>
> We'd continue to build HTML documentation as part of the workflow,
> naturally, as well as the man pages.
>
> I don't have any solid numbers, but I'm fairly sure most people use
> https://docs.couchdb.org/ or a locally installed copy for their
> documentation for CouchDB rather than the PDF documentation. I
> personally can't remember the last time I opened the docs in PDF form. I
> also have never seen anyone refer to the PDF docs on the mailing lists,
> IRC or Slack when asking for advice or support.
>
> I've also never seen anyone use or talk about the texinfo target, and
> I've not used them myself.
>
> Dropping this dependency will allow us to drop TeX/LaTeX from our build
> chain, which speeds up build times by about 90 seconds and reduces the
> size of containers currently being built for our Jenkins CI workflow.
> It also means CouchDB devs don't have to install 0.5-1.5GB worth of
> toolset.
>
> I've captured this in JIRA as
> https://issues.apache.org/jira/browse/COUCHDB-3329 and have PRs ready
> to fire off if people agree.
>
> Your thoughts?
>
> -Joan
>