pdf_paradise 0.1.43

data/bin/set_main_book

@@ -0,0 +1,7 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'pdf_paradise/set_main_book.rb'
+
+PdfParadise::SetMainBook.new(ARGV)

data/bin/set_title_of_this_pdf_file

@@ -0,0 +1,15 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# Remember that the first argument is the name of the .pdf file
+# in question and that the second argument is the title that you
+# wish to assign to it.
+# =========================================================================== #
+require 'pdf_paradise'
+
+if ARGV.size < 2
+  PdfParadise.show_correct_pdf_title_usage
+else
+  PdfParadise.set_title_of_this_pdf_file(ARGV.first, ARGV[1])
+end # Usage example: pdf_title foo.pdf "This is the new title"

data/doc/README.gen

@@ -0,0 +1,348 @@
+ADD_RUBY_HEADER
+ADD_TIME_STAMP
+
+This project can help with pdf-related activities, such as extracting
+a .pdf page, converting .pdf page, merging .pdf files, splitting
+.pdf files, setting the title of a .pdf page and similar actions.
+
+The project has to remain quite flexible. We may use external
+programs such as **ghoscript** or **qpdf*, or we may use pure
+ruby solutions, such as via the gem called **combine_pdf**,
+**prawn** or **hexapdf**.
+
+The file here (README.gen, respectively the generated file called
+**README.md**), will describe some of the components that make
+up this gem.
+
+## Rationale for making use of separate pdf-related projects
+
+There are many pdf-related tools if you look on the www. For
+example, we have prawn, we have qpdf, we have calibre, we
+have hexapdf, we have ghostscript, and many more applications.
+
+Some of these have unique features; and some of them have overlapping
+functionality, such as reading the content of .pdf files in a 
+simplified manner (number of pages, title, author and so forth).
+
+The PdfParadise project attempts to support as many different
+(open-source) projects as possible. It is also permissive to
+support closed source projects, provided that the code retains
+simple (and simple to change). The primary focus is on 
+open-source projects though.
+
+Why does the PdfParadise project attempt to support many different
+pdf-related projects?
+
+The main answer is quite simple. On Linux I have a lot of flexibility
+and can use literally any pdf-related project just fine. On Windows,
+however had, I am more restricted in what I can use. Not all programs
+are available on windows or can be easily compiled there. Thus, in
+order to allow the pdf_paradise .gem to work on windows, we need
+this flexibility.
+
+The reason why I added this subsection here in June 2021 was that
+I am slowly changing the sinatra-related part of the PdfParadise
+project, in order to embed the functionality into my main controller
+which is handled by the **Roebe** namespace. In that controller
+I wanted to easily offer pdf-related functionality "out of the
+box" when I start the sinatra-application on windows. Because I
+want to be able to offer pdf-related modifications on windows
+as well, the PdfParadise project had to become more flexible,
+so that a simple toplevel route, such as **/pdf**, will work
+properly, and lead to entry points (subroutes) that allow 
+us to tap into the features offered by the PdfParadise project.
+
+So, the summary is: the PdfParadise project must remain
+flexible in order to support a proper workflow on windows
+systems as well. (We could use WSL on windows, but not every
+computer has this available, so I am targeting "vanilla"
+windows really.)
+
+Note that one slight drawback is that the sinatra prat of
+the PdfParadise project now has a dependency on the
+**cyberweb** project. This is a trade-off - for me the
+more important part is long-term maintainability of
+the pdf_paradise project in the long run, so a unified
+code base had to be used in this regard.    
+
+## Converting a .pdf file to text
+
+Sometimes you may wish to have a text-file describing the content
+of a .pdf file, rather than the .pdf file itself.
+
+Via class **PdfParadise::ConvertPdfToText**, residing in the file
+at **pdf_paradise/convert_pdf_to_text.rb**, you can convert a
+.pdf file to a text file.
+
+Usage example from ruby, for the file called **foobar.pdf**:
+
+    PdfParadise::ConvertPdfToText.new(ARGV)
+    PdfParadise::ConvertPdfToText.new('foobar.pdf')
+
+You can also use the bin/ file from the commandline:
+
+    convert_pdf_to_text
+    convert_pdf_to_text foobar.pdf 
+
+There is also a ruby-gtk3 widget that offers the functionality
+from class **PdfParadise::ConvertPdfToText**, if the user
+has gtk3 installed and the ruby-bindings to it as well.
+
+You can start that ruby-gtk3 widget via:
+
+    convert_pdf_to_text --gui
+
+## Commandline usage
+
+You can use the **pdf_paradise** gem from the commandline, as
+the example above shows.
+
+For instance, say that you wish to modify **the title of a .pdf
+file**, you can use a commandline invocation such as via
+this way:
+
+    pdf_paradise --use-this-pdf-file=location_to_your_pdf_file.pdf --set_title="The title you want to use goes in here."
+
+You can also **shrink** a .pdf file, by using the commandline
+switch <b>--shrink-pdf-size-of=foobar.pdf</b> or just
+<b>--shrink</b>, such as:
+
+    pdf_paradise --shrink-pdf-size-of=foobar.pdf
+    pdf_paradise --shrink=foobar.pdf
+
+The <b>shrink</b> functionality is contained in the module-method
+<b>PdfParadise.reduce_size_of_this_pdf_file()</b>.
+
+## Storing the .pdf pages that are currently open
+
+If you need to store the .pdf files that are currently open,
+you can use the following commandline to do so:
+
+    pdfparadise --store-open-pdf-files
+
+This will attempt to store the full path to the .pdf files
+into a local file. That way you may also be able to batch-open
+these .pdf files at a later time, e. g. when you switch your
+window manager or after a reboot.
+
+## Deleting the last or the first page of a .pdf file
+
+You can use **class DeleteLastPageOfThisPdfFile**, more
+accurately called **class PdfParadise::DeleteLastPageOfThisPdfFile**,
+to ***delete the last page in a .pdf file***.
+
+In ruby code, you can invoke this like so:
+
+    require 'pdf_paradise'
+
+    PdfParadise::DeleteLastPageOfThisPdfFile.new('path_to_the_pdf_file/goes_in_here.pdf')
+
+or shorter:
+
+    require 'pdf_paradise'
+
+    PdfParadise.delete_last_page_of_this_pdf_file('foobar.pdf')
+
+A very similar API exists for deleting the first page of a given .pdf
+file, too.
+
+See:
+
+In ruby code, you can invoke this like so:
+
+    require 'pdf_paradise'
+
+    PdfParadise::DeleteFirstPageOfThisPdfFile.new('path_to_the_pdf_file/goes_in_here.pdf')
+
+or shorter:
+
+    require 'pdf_paradise'
+
+    PdfParadise.delete_first_page_of_this_pdf_file('foobar.pdf')
+
+## Converting markdown .md files to .pdf files
+
+If you use kramdown, prawn and kramdown-pdf-converter, then you
+can convert .md files on the commandline, via:
+
+    convert_markdown_to_pdf path_to_pdf_file_goes_here.pdf
+
+Install the necessary gems prior to using this commandline
+functionality.
+
+## sinatra interface
+
+Since as of April 2019 there is a minimal sinatra interface to the
+PdfParadise project. Consider this incomplete <b>work-in-progress</b>.
+
+To start it, try:
+
+    pdf_paradise --sinatra
+
+## Querying the title of a .pdf file
+
+<b>class PdfParadise::QueryPdfTitle</b> will report the title of
+any .pdf file that is passed into it, on the commandline.
+
+This currently depends on <b>exiftool</b> but at a later time,
+this may change to also allow a query via prawn or other tools.
+
+If you need to determine whether a given .pdf file has a title
+or whether it does not, you can use
+<b>PdfParadise.does_this_pdf_file_have_a_title?</b>, such
+as in:
+
+    PdfParadise.does_this_pdf_file_have_a_title? "foobar.pdf" # => true
+
+This method will return **true** if the .pdf file at hand has a
+title; and **false** otherwise.
+
+## Determining how many pages a given .pdf file has
+
+class **PdfParadise::PdfFileNTotalPages** can be used to query
+how many pages a given .pdf file has.
+
+The executable called **bin/n_pages** (thus, **n_pages**) can
+be used to query this, on the commandline.
+
+Example:
+
+    n_pages foobar.pdf
+
+Do note that the class requires the external program
+called **pdfinfo**.
+
+It is possible to query the number of pages in a given .pdf
+file without **pdfinfo**, but some .pdf files are a bit buggy,
+and **pdfinfo** is simply more reliable than the regex that
+was used until March 2020. So, past March 2020, the program
+**pdfinfo** is now used by default. Note that pdfinfo is
+part of the poppler software suite.
+
+You can also use the following toplevel API for this:
+
+    PdfParadise.n_pages? 'THE_PATH_TO_THE_PDF_FILE_GOES_IN_HERE.pdf'
+    PdfParadise.n_pages? 'foobar.pdf'
+
+## Splitting a single pdf file into individual several .pdf files
+
+You can use the following toplevel API to split up a single
+.pdf file into several .pdf files:
+
+    PdfParadise.burst(ARGV)
+    PdfParadise.burst('foobar.pdf')
+
+## Adding page numbers to .pdf files
+
+Via the combine_pdf gem it is now possible to add page numbers
+to .pdf files. This has a few limitations for complex .pdf files,
+due to combine_pdf having limitations in turn - but for simple
+.pdf files this should work really well.
+
+How to use that functionality?
+
+Consider using the following toplevel API:
+
+    PdfParadise.number_pages('this_file.pdf')
+
+The file called **this_file.pdf** has to exist in order for
+this to work, of course.
+
+The current default is to display the page numbers on the bottom
+right side. This is hardcoded, but you could modify the code
+to adapt to your needs; see also how combine_pdf does this.
+(You have to pass an option-hash.)
+
+## Compressing a .pdf file (optizime the size of a .pdf file)
+
+Sometimes you may have to reduce the filesize of a .pdf file,
+such as when you need to upload a .pdf file, and there is
+some file size limit otherwise.
+
+So, let us now assume that you **do** have a use case - you
+want to reduce the file size of a given .pdf file at hand.
+
+How can this be done?
+
+Well, there are several ways, but for the time being, only
+one way will be documented here - which is the one that
+requires **ghostscript**.
+
+The important parameter is the **dPDFSETTINGS** one. This
+one will determine the compression level, which ultimately 
+will affect the quality of the compressed .pdf file.
+
+class **PdfParadise::CompressThisPdfFile** can be of
+help here. Simply pass, as argument to .new(), the path
+of the local .pdf to that class.
+
+You can also use a toplevel method if you'd like to:
+
+    require 'pdf_paradise'
+    PdfParadise.compress_this_pdf_file
+    PdfParadise.compress_this_pdf_file('/foobar.pdf')
+
+## Merging pdf files
+
+class PdfParadise::MergePdf.new(ARGV) can be used for
+merging .pdf files.
+
+Currently <b>ghostscript</b> and <b>hexapdf</b> can be used for the
+merging step.
+
+Examples for both variants:
+
+    mergepdf one.pdf two.pdf --use-ghostscript
+    mergepdf one.pdf two.pdf --use-hexapdf
+
+(The two -- hyphen are mandatory for commandline arguments;
+otherwise it is assumed to be a locally existing .pdf file.)
+
+## GUI component of the PdfParadise project
+
+The PdfParadise project comes with some ruby-gtk3 specific
+GUIs, but a few ruby-gtk2 and ruby-tk bindings may exist
+as well. The gtk3 parts are the main GUI parts of this
+project though.
+
+You can start, from the commandline, the gtk-wrapper
+over the **split_pdf_file** functionality.
+
+In order to do this, do either one of the following:
+
+    pdf_paradise --gui
+    pdf_paradise --gtk
+
+This will require the **gtk_paradise** project and the gtk
+bindings, so quite a lot. **gem install gtk3** and
+**gem install gtk_paradise** should help.
+
+The GUI for class SplitPdfFile is called **PdfParadise::Gtk::SplitPdfFile**.
+The idea behind it is to allow you to determine some of the parameters
+in a graphical fashion.
+
+Since as of **September 2019**, there is also a mini-widget for quickly
+removing the first page of a .pdf file. This is really minimal right
+now and not very elegant; it may be improved in the future, but for
+the time being it is what it is. It is more a proof-of-concept that
+it can work.
+
+You can start this via:
+
+    require 'pdf_paradise/gui/gtk2/remove_first_page_of_pdf_file.rb'
+
+    PdfParadise.start_gtk_gui_remove_first_page_of_pdf_file
+
+Note that as of **January 2021** the gtk bindings will default to
+**ruby-gtk3**. Support for ruby-gtk2 will be retained, though,
+but new code may not necessarily be written for ruby-gtk2 in
+mind. ruby-gtk3 is now the main GUI target for this project.
+
+I am slowly porting the individual widgets.
+
+The following widgets have been ported so far:
+
+    PdfParadise::GUI::Gtk::StatisticsWidget # can be found under pdf_paradise/gui/gtk3/statistics_widget/statistics_widget.rb
+
+
+ADD_CONTACT_INFORMATION

data/doc/todo/todo.md

@@ -0,0 +1,2 @@
+- Add a converter-GUI.
+  From .docx to .pdf via libreoffice.

data/lib/pdf_paradise.rb

@@ -0,0 +1,5 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'pdf_paradise/requires/require_the_whole_project.rb'

data/lib/pdf_paradise/base/base.rb

@@ -0,0 +1,173 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'pdf_paradise/base/base.rb'; < ::PdfParadise::Base
+# =========================================================================== #
+require 'pdf_paradise/requires/colours_and_esystem_and_save_file_and_fileutils_and_opn.rb'
+
+module PdfParadise
+
+class Base # === PdfParadise::Base
+
+  require 'pdf_paradise/toplevel_methods/roebe.rb'
+  require 'pdf_paradise/constants/constants.rb'
+
+  include Colours
+
+  begin
+    require 'cliner'
+  rescue LoadError; end
+
+  begin
+    require 'save_file/module'
+  rescue LoadError; end
+
+  # ========================================================================= #
+  # === NAMESPACE
+  # ========================================================================= #
+  NAMESPACE = inspect
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize
+    reset
+  end
+
+  # ========================================================================= #
+  # === opnn
+  # ========================================================================= #
+  def opnn(i = @namespace)
+    if i.is_a? String
+      i = { namespace: i}
+    end
+    Opn.opn(i)
+  end
+
+  # ========================================================================= #
+  # === reset
+  # ========================================================================= #
+  def reset
+  end
+
+  # ========================================================================= #
+  # === write_what_into
+  # ========================================================================= #
+  def write_what_into(what, into)
+    SaveFile.write_what_into(what, into)
+  end; alias save_what_into write_what_into # === save_what_into
+
+  # ========================================================================= #
+  # === no_file_at
+  #
+  # This method (or its alias) can be used to notify the user that the
+  # given file does not exist at that given location (denoted by the
+  # argument called i).
+  # ========================================================================= #
+  def no_file_at(i)
+    e "No file called `#{sfile(i)}` exists at that target."
+  end; alias no_file_exists_at no_file_at # === no_file_exists_at
+
+  # ========================================================================= #
+  # === orange
+  # ========================================================================= #
+  def orange(i)
+    ::Colours.orange(i)
+  end
+
+  # ========================================================================= #
+  # === esystem
+  #
+  # Wrapper over Esystem.esystem().
+  # ========================================================================= #
+  def esystem(i)
+    Esystem.esystem(i)
+  end
+
+  # ========================================================================= #
+  # === is_on_roebe?
+  # ========================================================================= #
+  def is_on_roebe?
+    ::PdfParadise.is_on_roebe?
+  end
+
+  # ========================================================================= #
+  # === set_commandline_arguments
+  # ========================================================================= #
+  def set_commandline_arguments(i)
+    i = [i].flatten.compact
+    @commandline_arguments = i
+  end
+
+  # ========================================================================= #
+  # === return_files_from_the_commandline_arguments
+  #
+  # This method will return all existing files from the commandline
+  # arguments.
+  # ========================================================================= #
+  def return_files_from_the_commandline_arguments
+    @commandline_arguments.select {|entry|
+      File.file?(entry.to_s)
+    }
+  end
+
+  # ========================================================================= #
+  # === mv                                     (mv tag, move tag, rename tag)
+  # ========================================================================= #
+  def mv(old, new)
+    # ======================================================================= #
+    # We must check that both files exist, before we delete the new file,
+    # as we may otherwise end up without any .pdf file. This has happened
+    # to me in August 2019 when qpdf failed to do a conversion.
+    # ======================================================================= #
+    if File.file?(new) and File.file?(old)
+      File.delete(new)
+    end
+    if File.exist? old
+      FileUtils.mv(old, new)
+    else
+      e 'No file exists at '+sfile(old)+'.'
+    end
+  end; alias move_file mv # === move_file
+
+  # ========================================================================= #
+  # === return_pwd
+  # ========================================================================= #
+  def return_pwd
+    "#{Dir.pwd}/".squeeze('/')
+  end
+
+  # ========================================================================= #
+  # === commandline_arguments?
+  # ========================================================================= #
+  def commandline_arguments?
+    @commandline_arguments
+  end; alias input? commandline_arguments? # === input?
+
+  # ========================================================================= #
+  # === first_argument?
+  # ========================================================================= #
+  def first_argument?
+    @commandline_arguments.first
+  end
+
+  # ========================================================================= #
+  # === input_without_leading_hyphens?
+  #
+  # This method will return the input that will not begin with --.
+  # ========================================================================= #
+  def input_without_leading_hyphens?
+    @commandline_arguments.reject {|entry| entry.start_with? '--' }
+  end
+
+  # ========================================================================= #
+  # === return_commandline_arguments_starting_with_hyphens
+  # ========================================================================= #
+  def return_commandline_arguments_starting_with_hyphens(
+      i = @commandline_arguments
+    )
+    i.select {|entry| entry.start_with? '--' }
+  end; alias return_hyphen_arguments return_commandline_arguments_starting_with_hyphens # === return_hyphen_arguments
+
+end; end