The contents are nonresponsive. No tool can fix a native
responsiveness issues. I am familiar with those tools. The questions
is why work so hard when you have the HTML already?
I'm afraid I don't understand this argument. It is true that PDFs are
not responsive without software assistance, but HTML documents when
printed (e.g. CTRL+P) do not have any way of generating the Appendix /
outlinks to related sections etc. Yet we still have HTML documentation.
IMO this simply means they are not mutually exclusive.
This is demonstrably true, the document margins are against quite a
few technical document typography rules (mostly how page setup and
typeface choices are done). It is as it is because the documentation
is also following an indentation format very much like Python code
which uses whitespace too generously. The document itself is quite an
eyesore if you care about those things.np.einsum is a prime example
how it shouldn't render in a PDF document. All choices are coming from
the indentation of markdown. Because it uses none of the advantages of
a PDF. That is typography and font layout. It cannot use it because
the source is not providing context. Because it is coming from a
function signature. This is also related to Markdown comment below.
About this, the full page layout on the HTML pages has exactly the same
amount of whitespace. It can be argued that for a full width layout
there is exactly the same whitespace and indentation.
Additionally, even trying to print out say, `np.einsum` will first have
3 pages of the sidebar when using a naive CTRL+P approach.
The argument that the typography is poor goes beyond the documentation
format.
In fact, even the "responsiveness" is rather overrated at the moment.
With a mobile device again the first few screenfulls are simply the
sidebar with routines and other things. After which there's still
whitespace, and things are still just as indented as in the PDF. Only
now I also don't have a global TOC which is easy to see.
The assertion that there is parity between serving ~2000 pages of
documentation as HTML and ZIP files as opposed to a PDF seems to be
flawed from the get go.
If you want to have a proper doc effort, that is a whole another story
and I would love to have that but this doc generated PDF is not worth
of any nonnegligable value.
I should add that NumPy does indeed have a dedicated docs team and
consolidated effort. As mentioned earlier we meet regularly about these
issues and it would be nice if the meetings are not unequivocally
sidestepped by the mailing list. We also apply for funding (GSoD /
NumFocus SDG) for our docs.
I understand there are frustrations with the PDF, but I am still not
convinced at this point that the HTML versions are even at par with the
PDF experience.
It is nice that I have the time and ability to generate my documentation
locally for my niche needs should I so wish it. It is less nice that we
assume that it must be niche and everyone would have the same energy
because HTML is theoretically more responsive, even though our docs are
not.
-- Rohit
On 23 May 2022, at 11:08, Ilhan Polat wrote:
On Mon, May 23, 2022 at 11:12 AM Rohit Goswami
<rgosw...@quansight.com>
wrote:
I am unaware of the state of the SciPy documentation at the time it
was
dropped. However, many of these arguments do not seem to apply to the
NumPy
documentation hosted at https://numpy.org/doc/.
They were almost identical, same machinery (like most things). Well
this is
subjective but the typography is unfit for any code based format.
The typography is \\subsubpar (as a TeX person should say) and just
an
eyesore, this actually matters a lot more than you would assume and
unreadable in mobile without constant zooming because of
nonresponsive
format
This is a valid concern, but there are third-party tools to deal with
reflow (both at the mobile level and by preprocessing like with
k2pdfopt:
https://www.willus.com/k2pdfopt/)
The contents are nonresponsive. No tool can fix a native
responsiveness
issues. I am familiar with those tools. The questions is why work so
hard
when you have the HTML already?
There are no broken links in our User Guide, and even external links
(e.g.
PyObject links to the Python documentation) work. Internal links to
different parts of the PDF also work.
I have not read our Reference Guide cover to cover in a while (other
than
the NumPy-C API chapter) but I do not remember any backticks
anywhere.
Please correct me if this is incorrect.
OK this one was on me. I've updated the reader and now things went
back to
normal. Sorry for the noise.
This isn't the case for Firefox's PDF viewer and others I have tried
(Adobe, Zathura). Though on Linux most pdf copy-pastes can be a
little
difficult.
All mentioned viewers fail to retain the format of the code and copy
as
text. You should paste it to somewhere to get the problem. Unless it
is
single line in the examples the rest is not really working properly.
In
case you are not familiar there are quite a number of ways to fix this
but
definitely not worth the effort.
Untrue, our typography and layout might not be perfect but we do not
have
a lot of empty space.
This is demonstrably true, the document margins are against quite a
few
technical document typography rules (mostly how page setup and
typeface
choices are done). It is as it is because the documentation is also
following an indentation format very much like Python code which uses
whitespace too generously. The document itself is quite an eyesore if
you
care about those things.np.einsum is a prime example how it shouldn't
render in a PDF document. All choices are coming from the indentation
of
markdown. Because it uses none of the advantages of a PDF. That is
typography and font layout. It cannot use it because the source is not
providing context. Because it is coming from a function signature.
This is
also related to Markdown comment below.
We have a reasonable 30 minute timeout for the pdf build and we have
discussed running this less frequently.
This doesn't change the fact that you are downloading way too many
complex
tools and moving images that are bloated. Just because it is free does
not
justify its use. It is just a huge waste to repeat that excessive
compilation each and every time. I would also say it is a bit on the
irresponsible side.
Also can be mitigated, we can shift to tectonic or simply use a
custom
texlive install to have less packages (for the size issue).
No. This is still a very large payload mainly due to the typography
tools
are used and their dependencies. Maintaining a custom TeXLive is just
asking for trouble since the packages are updated very frequently (I
know
because we tried this many times at work to keep a mobile Receipt
generator).
It is a very unstable workflow and errors out depending on the
planets
alignment because, again, it is coming from an awkward Markdown
source
which is not designed for. Becomes very annoying for maintainers to
see it
fail for otherwise a perfectly valid code.
We don't have markdown sources?
What I mean is that LaTeX source is text-based with context in it. But
we
are providing markdown sources. This causes problems in the meantime
both
in translation and also layout.
I understand that perhaps SciPy's documentation was in far worse
shape
than NumPy, but we shouldn't paint with a broad brush
That's not true. They are almost identical. These are common issues
that
still exists in the NumPy version. To be honest, it is very hard to
make a
case for PDF in its given condition. You can still compile and use it.
We
shouldn't continue bothering with it at the CI level just because
there is
a marginal interest in it. I am not ranting about NumPy because SciPy.
This
is a very bad TeX design and to fix it we have to get away from
auto-doc
generation which I am sure none of us want for now. That is
unfortunately
how good docs are now today, mathworks constantly being praised about
it
despite its notoriety. Hence I don't see any case for keeping
generating
this PDF. If you want to have a proper doc effort, that is a whole
another
story and I would love to have that but this doc generated PDF is not
worth
of any nonnegligable value. And if you think it is then you can
generate it
yourself. The tools are not going to be removed anyways.
_______________________________________________
NumPy-Discussion mailing list -- numpy-discussion@python.org
To unsubscribe send an email to numpy-discussion-le...@python.org
https://mail.python.org/mailman3/lists/numpy-discussion.python.org/
Member address: rgosw...@quansight.com
_______________________________________________
NumPy-Discussion mailing list -- numpy-discussion@python.org
To unsubscribe send an email to numpy-discussion-le...@python.org
https://mail.python.org/mailman3/lists/numpy-discussion.python.org/
Member address: arch...@mail-archive.com
