[Documentation / Suggestion] Add FAQ-style entries to hexapdf

[rubyFeedback]

Sers Thomas,

I recently had indirect issues with regards to hexapdf, in that this was not hexapdf's fault (so no worries here), but me trying to analyse .pdf files in a somewhat constrained environment (an oldschool .cgi page).

For instance, I specifically got errors like that:

  <internal:/home/Programs/Ruby/3.3.3/lib/ruby/site_ruby/3.3.0/rubygems/core_ext/kernel_require.rb>:136:in `require': cannot load such file -- hexapdf/cli (LoadError)
  from <internal:/home/Programs/Ruby/3.3.3/lib/ruby/site_ruby/3.3.0/rubygems/core_ext/kernel_require.rb>:136:in `require'
  from /usr/local/bin/hexapdf:4:in `<main>'

That may also relate from rubygems itself, rather than hexapdf as such.

And prior to that, ruby told me it could not find hexapdf at all. Whereas when I used hexapdf from the commandline, before the above error (e. g. the error now, where hexapdf could not be found), hexapdf was working just fine. So there was some issue in regards to the environment here. (I also got wrong encoding issues, which also was not the fault of hexapdf; on the commandline I had UTF-8 encoding, via the .cgi file I had ASCII-8BIT, no clue how this came to be but I simply used .force_encoding() as a hard "fix", and that seems to have worked.)

I am putting all pdf-code I use into a specific subproject. However had, I also was mostly calling "hexapdf" binary, e. g. to find out how many pages are in the given .pdf file. So, as that environment suddenly could no longer find the hexapdf binary, I thought it would be time to rewrite all the calls to the binary into pure ruby instead. So I need (or needed) the equivalent functionality from the hexapdf-library instead.

This is just some lengthy background explanation, to explain from which point I am coming from. :)

Ok so ... I have some direct calls to the hexapdf binary which I want to replace in pure ruby, using hexapdf API now.

First simple task on my todo list here was to find out how many pages are in the given .pdf file.

I thus had a look at the official docu here:

https://hexapdf.gettalong.org/documentation/basics/index.html

I have to say: the information is excellent. I have only a slight layout issue, in that I am using a widescreen monitor, and everything seems to be centered (that's fine), but like 30% of the page on the left is white, and 20% on the right is white. So I am kind of not seeing the optimal layout here, in my opinion.

You may not understand what I intend to convey, so here is the picture:

https://i.imgur.com/z6hgMNy.png

Perhaps the margin could be changed a bit, for widescreen users (for smartphone users the above may be fine). So like ... rather than 30% to the left, you could expand it a bit to 25%, and on the right rather than ~20%, it could be 15%. In other words, to make the central content spread out a bit, in particular the main content area on the right side (index is not so important, although I think it also is too narrow).

Anyway that's a side report, not so important, so back to the API documentation.

On that page I linked above, you show this example via Document.open:

doc = HexaPDF::Document.open("test.pdf") => <HexaPDF::Document:1980>

And that works! (At first I was a bit confused why .new does not accept a .pdf file, but the API documentation mentions the alternative, so that is fine.)

Ok ... how to obtain how many pages to find?

Well, I did not read any more documentation, I just tried a few methods - and like the second or third try, I figured it out on my own. That's the power of ruby there!

doc.pages => #<HexaPDF::Document::Pages:0x00007f1347b5e030 @document=<HexaPDF::Document:1980>

doc.pages.size => 86

So, we get all pages via .pages and then we can simply call .size on the result. Et voila!

I still have to find solutions to the other uses of bin/hexapdf, but for now this should suffice. (I do this to actually embed a "widget" for display on websites in general; the .cgi file actually just autogenerates a .html file, which then has static information about all local .pdf files, and I use this primarily for support of an elderly person having stored tons of different .pdf files. So, kind of like an "overview" .html page that shows lots of information about different .pdf files.)

Now my suggestion though:

Would it be possible or desired to present some kind of "Usage FAQ" of hexapdf, but one that is short and to the point? For instance:

"Determine how many pages are in a given .pdf file:"

And then the code would be shown, such as the one I mentioned above.

The same could be done with many other examples - a bit like a mini StackOverflow guide for how to use hexapdf for common tasks; and perhaps in a second step for not so common tasks.

Ideally this could be a single .md file which content you can then just simply show on the homepage. Alternatively you could perhaps use meta-tags in whatever format you maintain the API documentation and then use ruby to retrieve these all into a standalone .md file or so. Not sure how you store the API documentation; for my own gems I typically store information in a file called README.gen (.gen for generator), which I then use to generate a README.md standalone file, and the ruby script that converts this, also supports some custom "macros" I use, to add additional information. But perhaps you just use markdown files, so a single .md file may be better.

I am not sure whether a FAQ is worth your time, but perhaps other ruby users of hexapdf may also benefit for this, so I naturally leave all decisions in this regard up to you, of course. Please feel free to close this issue at any moment in time.

TL;DR: Please consider adding a FAQ-ish style "usage example". (A bit similar to zenspider's quickref, but adjusted to hexapdf's use cases rather than zenspider's quickref to ALL of ruby itself.)

PS: If that already exists then perhaps it could be mentioned in the introduction too, such as "for a quick overview of many different examples, consider visiting the following link" or something like that, and then link in to that FAQ or Example.md file described above.

[gettalong]

Hi,

thanks for detailed issue!

Regarding the website layout: The width of the main content is chosen so that the line length of the paragraphs is not too much to aid reading. Once lines get longer it is harder to read everything. You can observe the same behaviour here on Github where the issue contents is also constraint to a manageable line length. However, comparing the HexaPDF website with others I agree that it could be a bit wider.

As for the main issue: There are currently some How-To sections like this under the main headings. Those generally show how to do more complex stuff. An FAQ section like you mentioned doesn't currently exist. However, I can see the value in that. Let me think about how to do this and I will come back to you.

Thank you for the suggestion!

[gettalong]

@rubyFeedback The changed width is already live on the website since I had to do a HexaPDF release anyway :) I hope that works better for you now.