[ELPA] New package: toc-mode

[ELPA] New package: toc-mode

[dalanicolai]

[-- Attachment #1: Type: text/plain, Size: 1221 bytes --]

This package has been for a while on MELPA now, but it would be nice if it
could be moved to ELPA. The source can be found at
https://github.com/dalanicolai/toc-mode.

I would like to mention that the PDF functionalities largely depend on
pdf-tools, which is not on
ELPA of course (doc-view unfortunately does not provide the right
features). I am not sure
if that somehow is a problem.

The package description is:

Create, cleanup, add and manage Table Of Contents (TOC) of pdf and djvu
documents with Emacs

TOC-mode is a package for creating, cleaning, adding and managing the Table
Of Contents (TOC) of pdf and djvu documents.


Quite some (usually older, but also newer) digital books, come without a
digital Table of Contents.

However, such TOC is often quite convenient to have (especially for
researchers/students who would like to skim/navigate books quickly).


This package provides functionalities for easily extracting and preparing
from text contents, and subsequently adding to documents, digital Tables of
Contents.


Please let me know if the package is suitable for ELPA, and then what else
is needed to make it

ready for ELPA (although I guess it is already ready for publishing on
ELPA).


Thanks!

[-- Attachment #2: Type: text/html, Size: 1526 bytes --]

Re: [ELPA] New package: toc-mode

[Jean Louis]

* dalanicolai <dalanicolai@gmail.com> [2022-09-20 17:59]:
> This package has been for a while on MELPA now, but it would be nice if it
> could be moved to ELPA. The source can be found at
> https://github.com/dalanicolai/toc-mode.
> 
> I would like to mention that the PDF functionalities largely depend on
> pdf-tools, which is not on
> ELPA of course (doc-view unfortunately does not provide the right
> features). I am not sure
> if that somehow is a problem.
> 
> The package description is:
> 
> Create, cleanup, add and manage Table Of Contents (TOC) of pdf and djvu
> documents with Emacs
> 
> TOC-mode is a package for creating, cleaning, adding and managing the Table
> Of Contents (TOC) of pdf and djvu documents.

I did not know about the package. Though when I read `toc-mode' I got
idea that it will generate table of contents for various lightweight
markup languages, such as markdown, txt2tags, restructured text,
asciidoc, org and similar.

My suggestion is that you rename it to indicate it is about PDF, like
`toc-pdf-mode'.

-- 
Jean

Take action in Free Software Foundation campaigns:
https://www.fsf.org/campaigns

In support of Richard M. Stallman
https://stallmansupport.org/

Re: [ELPA] New package: toc-mode

[Emanuel Berg]

Jean Louis wrote:

> I did not know about the package. Though when I read
> `toc-mode' I got idea that it will generate table of
> contents for various lightweight markup languages, such as
> markdown, txt2tags, restructured text, asciidoc, org
> and similar.
>
> My suggestion is that you rename it to indicate it is about
> PDF, like `toc-pdf-mode'.

Maybe but the TeX/LaTeX people recognize ToC ...

It's like people into sports know MVP and people into war
vehicles and tech know ACVs and UAVs.

Here is some creative TeX for YOU from a seasoned PRO
(actually those where 2 out of 4 times I ever did it).
That's interesting, right? You don't find that creative C from
a guy who wrote 4 C programs. Does it work different for
different languages or did I happen to have two or three
seasons when I was just in a league of my own?

  https://dataswamp.org/~incal/hs-linux/docs/report/report.pdf (PDF)
  https://dataswamp.org/~incal/hs-linux/docs/report/report.tex (LaTeX)
  https://dataswamp.org/~incal/borta/borta.pdf (PDF)
  https://dataswamp.org/~incal/borta/ (LaTeX)

But OTOH I still understand all my C, ever and all ...

-- 
underground experts united
https://dataswamp.org/~incal

Re: [ELPA] New package: toc-mode

[Philip Kaludercic]

dalanicolai <dalanicolai@gmail.com> writes:

> This package has been for a while on MELPA now, but it would be nice if it
> could be moved to ELPA. The source can be found at
> https://github.com/dalanicolai/toc-mode.
>
> I would like to mention that the PDF functionalities largely depend on
> pdf-tools, which is not on
> ELPA of course (doc-view unfortunately does not provide the right
> features). I am not sure
> if that somehow is a problem.

Is there a reason it doesn't depend on pdf-tools?

> The package description is:
>
> Create, cleanup, add and manage Table Of Contents (TOC) of pdf and djvu
> documents with Emacs
>
> TOC-mode is a package for creating, cleaning, adding and managing the Table
> Of Contents (TOC) of pdf and djvu documents.
>
>
> Quite some (usually older, but also newer) digital books, come without a
> digital Table of Contents.
>
> However, such TOC is often quite convenient to have (especially for
> researchers/students who would like to skim/navigate books quickly).
>
>
> This package provides functionalities for easily extracting and preparing
> from text contents, and subsequently adding to documents, digital Tables of
> Contents.

I guess it sounds nice to have.

> Please let me know if the package is suitable for ELPA, and then what else
> is needed to make it

The first thing that would have to be changed is the "Version" header.
It is currently set to "0" which is a MELPA-ism but ELPA interprets as
"unreleased".  Just bump it to whatever version greater than 0 that you
prefer.  Every time you bump the version tag, a new release will be
built and distributed.

> ready for ELPA (although I guess it is already ready for publishing on
> ELPA).
>
>
> Thanks!

Re: [ELPA] New package: toc-mode

[dalanicolai]

[-- Attachment #1: Type: text/plain, Size: 2096 bytes --]

That might be a typo, the package of course does depend on pdf-tools.

Indeed the package can be released immediately (without prior extra
development),
so I will increase that version number then.


On Tue, 20 Sept 2022 at 19:37, Philip Kaludercic <philipk@posteo.net> wrote:

> dalanicolai <dalanicolai@gmail.com> writes:
>
> > This package has been for a while on MELPA now, but it would be nice if
> it
> > could be moved to ELPA. The source can be found at
> > https://github.com/dalanicolai/toc-mode.
> >
> > I would like to mention that the PDF functionalities largely depend on
> > pdf-tools, which is not on
> > ELPA of course (doc-view unfortunately does not provide the right
> > features). I am not sure
> > if that somehow is a problem.
>
> Is there a reason it doesn't depend on pdf-tools?
>
> > The package description is:
> >
> > Create, cleanup, add and manage Table Of Contents (TOC) of pdf and djvu
> > documents with Emacs
> >
> > TOC-mode is a package for creating, cleaning, adding and managing the
> Table
> > Of Contents (TOC) of pdf and djvu documents.
> >
> >
> > Quite some (usually older, but also newer) digital books, come without a
> > digital Table of Contents.
> >
> > However, such TOC is often quite convenient to have (especially for
> > researchers/students who would like to skim/navigate books quickly).
> >
> >
> > This package provides functionalities for easily extracting and preparing
> > from text contents, and subsequently adding to documents, digital Tables
> of
> > Contents.
>
> I guess it sounds nice to have.
>
> > Please let me know if the package is suitable for ELPA, and then what
> else
> > is needed to make it
>
> The first thing that would have to be changed is the "Version" header.
> It is currently set to "0" which is a MELPA-ism but ELPA interprets as
> "unreleased".  Just bump it to whatever version greater than 0 that you
> prefer.  Every time you bump the version tag, a new release will be
> built and distributed.
>
> > ready for ELPA (although I guess it is already ready for publishing on
> > ELPA).
> >
> >
> > Thanks!
>

[-- Attachment #2: Type: text/html, Size: 2866 bytes --]

Re: [ELPA] New package: toc-mode

[Emanuel Berg]

dalanicolai wrote:

> Indeed the package can be released immediately (without
> prior extra development), so I will increase that version
> number then.

Maybe do that even more, for good measure?

-- 
underground experts united
https://dataswamp.org/~incal

Re: [ELPA] New package: toc-mode

[dalanicolai]

[-- Attachment #1: Type: text/plain, Size: 388 bytes --]

Increasing the version number?

On Wed, 21 Sept 2022 at 13:13, Emanuel Berg <incal@dataswamp.org> wrote:

> dalanicolai wrote:
>
> > Indeed the package can be released immediately (without
> > prior extra development), so I will increase that version
> > number then.
>
> Maybe do that even more, for good measure?
>
> --
> underground experts united
> https://dataswamp.org/~incal
>
>
>

[-- Attachment #2: Type: text/html, Size: 799 bytes --]

Re: [ELPA] New package: toc-mode

[dalanicolai]

[-- Attachment #1: Type: text/plain, Size: 619 bytes --]

>
> dalanicolai wrote:
>
> > Indeed the package can be released immediately (without
> > prior extra development), so I will increase that version
> > number then.
>
> Maybe do that even more, for good measure?


Increasing the version number?

(sorry... again)

On Wed, 21 Sept 2022 at 13:13, Emanuel Berg <incal@dataswamp.org> wrote:

> dalanicolai wrote:
>
> > Indeed the package can be released immediately (without
> > prior extra development), so I will increase that version
> > number then.
>
> Maybe do that even more, for good measure?
>
> --
> underground experts united
> https://dataswamp.org/~incal
>
>
>

[-- Attachment #2: Type: text/html, Size: 1267 bytes --]

Re: [ELPA] New package: toc-mode

[Philip Kaludercic]

dalanicolai <dalanicolai@gmail.com> writes:

> That might be a typo, the package of course does depend on pdf-tools.
>
> Indeed the package can be released immediately (without prior extra
> development),
> so I will increase that version number then.

Of course we a talking about GNU ELPA, all significant have to have had
signed the CA.  Do you know if that is the case?

Re: [ELPA] New package: toc-mode

[Stefan Kangas]

dalanicolai <dalanicolai@gmail.com> writes:

> I would like to mention that the PDF functionalities largely depend on
> pdf-tools, which is not on ELPA of course (doc-view unfortunately does
> not provide the right features). I am not sure if that somehow is a
> problem.

It's not the ideal situation of course (it'd be better if all packages
were in GNU ELPA), but we also don't have any rule that GNU ELPA
packages can't depend on packages in NonGNU ELPA.

(That said, it would of course be good to extend doc-view to support
this use case at some point.)

> This package provides functionalities for easily extracting and preparing
> from text contents, and subsequently adding to documents, digital Tables of
> Contents.

Sounds useful, thanks.

> Please let me know if the package is suitable for ELPA, and then what
> else is needed to make it ready for ELPA (although I guess it is
> already ready for publishing on ELPA).

We don't really have any strict criteria.  It's suitable if it's useful,
unless there are some overriding technical or ethical concerns (e.g. if
the package recommends non-free software) that we're aware of.

Re: [ELPA] New package: toc-mode

[Jose A Ortega Ruiz]

On Tue, Sep 20 2022, dalanicolai wrote:

> This package has been for a while on MELPA now, but it would be nice if it
> could be moved to ELPA. The source can be found at
> https://github.com/dalanicolai/toc-mode.
>
> I would like to mention that the PDF functionalities largely depend on
> pdf-tools, which is not on ELPA of course (doc-view unfortunately does
> not provide the right features). I am not sure if that somehow is a
> problem.

for doc-view, if you're willing to rely on "mutool" (a cli program that
is installed with mupdf), one can extract an outline with something
similar to this function:

  https://codeberg.org/jao/elibs/src/branch/main/lib/doc/jao-pdf.el#L48    

i then for instance use it to provide imenu jumping with this code:

  https://codeberg.org/jao/elibs/src/branch/main/lib/doc/jao-doc-view.el#L50

just in case you'd like to add something like that to your package (all
in all it's just a dozen lines per function).

cheers,
jao
-- 
Who knows what Columbus would have discovered if America hadn't got in the
way. -Stanislaw J. Lec, poet and aphorist (1909-1966)

Re: [ELPA] New package: toc-mode

[dalanicolai]

[-- Attachment #1: Type: text/plain, Size: 1894 bytes --]

The package is for extracting a TOC when the document does not yet contain
one.
But it includes a command also to extract the TOC if the document already
has one
(so that it can be altered)

I am working on some alternative/upgrade to doc-view, pdf-tools and
djvu.el, although
 it might take a while as it is a lot of work. I did not make a project
page yet, but will
probably post a link to it soon here. Indeed, for now it provides imenu
commands for
pdf and djvu documents. If you like, I could drop the code for creating the
imenu index
 here (you have it already of course, but you might like to see different
solutions). Just,
let me know if you are interested.



On Tue, 20 Sept 2022 at 23:30, Jose A Ortega Ruiz <jao@gnu.org> wrote:

> On Tue, Sep 20 2022, dalanicolai wrote:
>
> > This package has been for a while on MELPA now, but it would be nice if
> it
> > could be moved to ELPA. The source can be found at
> > https://github.com/dalanicolai/toc-mode.
> >
> > I would like to mention that the PDF functionalities largely depend on
> > pdf-tools, which is not on ELPA of course (doc-view unfortunately does
> > not provide the right features). I am not sure if that somehow is a
> > problem.
>
> for doc-view, if you're willing to rely on "mutool" (a cli program that
> is installed with mupdf), one can extract an outline with something
> similar to this function:
>
>   https://codeberg.org/jao/elibs/src/branch/main/lib/doc/jao-pdf.el#L48
>
>
> i then for instance use it to provide imenu jumping with this code:
>
>
> https://codeberg.org/jao/elibs/src/branch/main/lib/doc/jao-doc-view.el#L50
>
> just in case you'd like to add something like that to your package (all
> in all it's just a dozen lines per function).
>
> cheers,
> jao
> --
> Who knows what Columbus would have discovered if America hadn't got in the
> way. -Stanislaw J. Lec, poet and aphorist (1909-1966)
>

[-- Attachment #2: Type: text/html, Size: 2777 bytes --]

Re: [ELPA] New package: toc-mode

[Jean Louis]

* dalanicolai <dalanicolai@gmail.com> [2022-09-21 10:13]:
> The package is for extracting a TOC when the document does not yet contain
> one.
> But it includes a command also to extract the TOC if the document already
> has one
> (so that it can be altered)
> 
> I am working on some alternative/upgrade to doc-view, pdf-tools and
> djvu.el, although
>  it might take a while as it is a lot of work. I did not make a project
> page yet, but will
> probably post a link to it soon here. Indeed, for now it provides imenu
> commands for
> pdf and djvu documents. If you like, I could drop the code for creating the
> imenu index
>  here (you have it already of course, but you might like to see different
> solutions). Just,
> let me know if you are interested.

I am interested, send me the list of features that your package provides.

-- 
Jean

Take action in Free Software Foundation campaigns:
https://www.fsf.org/campaigns

In support of Richard M. Stallman
https://stallmansupport.org/

Re: [ELPA] New package: toc-mode

[Jose A Ortega Ruiz]

On Wed, Sep 21 2022, dalanicolai wrote:

> I am working on some alternative/upgrade to doc-view, pdf-tools and
> djvu.el, although it might take a while as it is a lot of work. I did
> not make a project page yet, but will probably post a link to it soon
> here. Indeed, for now it provides imenu commands for pdf and djvu
> documents. If you like, I could drop the code for creating the imenu
> index here (you have it already of course, but you might like to see
> different solutions). Just, let me know if you are interested.

yes, i am.  i put together that code of mine as a quick hack, and though
it's been serving me well, i'm pretty sure there's ample room for
improvement.

thanks,
jao
-- 
We confess our little faults to persuade people that we have no large ones.
 -Francois de La Rochefoucauld, writer (1613-1680)

Re: [ELPA] New package: toc-mode

[Stefan Monnier]

[-- Attachment #1: Type: text/plain, Size: 1572 bytes --]

> This package has been for a while on MELPA now, but it would be nice if it
> could be moved to ELPA. The source can be found at
> https://github.com/dalanicolai/toc-mode.
>
> I would like to mention that the PDF functionalities largely depend on
> pdf-tools, which is not on ELPA of course (doc-view unfortunately does
> not provide the right features). I am not sure if that somehow is
> a problem.

Since pdf-tools is in NonGNU ELPA, this is not a problem, no.

> The package description is:
>
> Create, cleanup, add and manage Table Of Contents (TOC) of pdf and djvu
> documents with Emacs

Sounds handy, thanks.  FWIW, I tend to agree with Jean that the name
suggests its purpose is more general (more like a kind of speedbar/imenu
maybe).  Furthermore the "-mode" part of the name suggests it's a major
mode to edit some standard "toc" files rather than an actual tool to
extract things for non-toc files and then edit those files.

So I'd support a renaming (in case you're out of ideas, maybe
"toc-edit/edit-doc-toc", tho maybe "create-doc-toc" is more precise
since it doesn't seem to care very much about editing an existing toc),
but I don't have a strong opinion about it.

Once you've made up your mind about the package name, let me know so
I can add it to `elpa.git`.

> ready for ELPA (although I guess it is already ready for publishing on
> ELPA).

Indeed, except for the copyright line which needs to be adjusted.

The patch below does that along with the obligatory cosmetic tweaks.
I also include the remaining compilation warnings.


        Stefan

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: toc-mode.patch --]
[-- Type: text/x-diff, Size: 4581 bytes --]

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000000..26152f633d
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,3 @@
+*.elc
+/toc-mode-autoloads.el
+/toc-mode-pkg.el
diff --git a/toc-mode.el b/toc-mode.el
index 11a70566fd..7817c5d842 100644
--- a/toc-mode.el
+++ b/toc-mode.el
@@ -1,5 +1,5 @@
 ;;; toc-mode.el --- Manage outlines/table of contents of pdf and djvu documents  -*- lexical-binding: t; -*-
-;; Copyright (C) 2020  Daniel Laurens Nicolai
+;; Copyright (C) 2020-2022  Free Software Foundation, Inc.
 
 ;; Author: Daniel Laurens Nicolai <dalanicolai@gmail.com>
 ;; Version: 0
@@ -235,13 +235,11 @@
 (defcustom toc-replace-original-file t
   "For PDF include TOC and replace old PDF file.
 For DJVU the old DJVU file is replaced by default"
-  :type 'boolean
-  :group 'toc)
+  :type 'boolean)
 
 (defcustom toc-destination-file-name "pdfwithtoc.pdf"
   "Filename for new PDF if `toc-replace-original-file' is nil."
-  :type 'file
-  :group 'toc)
+  :type 'file)
 
 (defcustom toc-ocr-languages nil
   "Languages used for extraction with ocr.
@@ -249,21 +247,18 @@ Should be one or multiple language codes as recognized
 by tesseract -l flag, e.g. eng or eng+nld. Use
 \\[execute-extended-command] `toc-list-languages' to list the
 available languages."
-  :type 'string
-  :group 'toc)
+  :type 'string)
 
 (defcustom toc-handyoutliner-path nil
   "Path to handyoutliner executable.
 String (i.e. surround with double quotes). See
 URL`http://handyoutlinerfo.sourceforge.net/'."
-  :type 'file
-  :group 'toc)
+  :type 'file)
 
 (defcustom toc-file-browser-command nil
   "Command to open file browser.
 String (i.e. surround with double quotes)."
-  :type 'file
-  :group 'toc)
+  :type 'file)
 
 ;;;; pdf.tocgen
 ;;;###autoload
@@ -276,7 +271,7 @@ document's directory. You will be prompted to enter the LEVEL
 number. The highest level should have number 1, the next leve
 number 2 etc."
   (interactive "nWhich level you are setting (number): ")
-  (let* ((page (eval (pdf-view-current-page)))
+  (let* ((page (pdf-view-current-page))
          (filename (url-filename (url-generic-parse-url buffer-file-name)))
          (pdfxmeta-result (shell-command
                            (format "pdfxmeta --auto %s --page %s '%s' \"%s\" >> recipe.toml"
@@ -417,7 +412,7 @@ Prefix with numeric ARG prefix to apply to the next ARG lines."
   "Cleanup extracted Table Of Contents by running a series of cleanup functions.
 It executes the following steps:
 1. insert a Contents entry with pagenumber CONTENTS-PAGE
-2. delete subsequent lines containing the string 'contents'
+2. delete subsequent lines containing the string \"contents\"
 3. tries to delete redundant dots
 4. deletes lines that containi only roman numerals and linefeed characters
 5. deletes
@@ -560,7 +555,7 @@ unprocessed text."
               ;;                 nil
               ;;                 (number-to-string page)
               ;;                 (image-property djvu-doc-image :data))))))
-              (apply 'call-process
+              (apply #'call-process
                      (append (list "tesseract" nil (list buffer nil) nil file)
                              args))
               (setq page (1+ page))))
@@ -620,7 +615,7 @@ Prompt for startpage and endpage and print OCR output to new buffer."
                                                nil
                                                (number-to-string page)
                                                (image-property djvu-doc-image :data))))))
-              (apply 'call-process
+              (apply #'call-process
                      (append (list "tesseract" nil (list buffer nil) nil file)
                              args))
               (setq page (1+ page))))
@@ -634,12 +629,12 @@ Prompt for startpage and endpage and print OCR output to new buffer."
 ;;;; toc major modes
 
 (when (require 'pdf-tools nil t)
-  (define-key pdf-view-mode-map (kbd "C-c C-e") 'toc-extract-pages)
-  (define-key pdf-view-mode-map (kbd "C-c e") 'toc-extract-pages-ocr))
+  (define-key pdf-view-mode-map (kbd "C-c C-e") #'toc-extract-pages)
+  (define-key pdf-view-mode-map (kbd "C-c e") #'toc-extract-pages-ocr))
 
 (when (require 'djvu nil t)
-  (define-key djvu-read-mode-map (kbd "C-c C-e") 'toc-extract-pages)
-  (define-key djvu-read-mode-map (kbd "C-c e") 'toc-extract-pages-ocr))
+  (define-key djvu-read-mode-map (kbd "C-c C-e") #'toc-extract-pages)
+  (define-key djvu-read-mode-map (kbd "C-c e") #'toc-extract-pages-ocr))
 
 (defvar toc-cleanup-mode-map
   (let ((map (make-sparse-keymap)))

[-- Attachment #3: toc-mode.warnings --]
[-- Type: text/plain, Size: 1004 bytes --]

Byte compiling packages/toc-mode/toc-mode.el

In toc--cleanup-lines-roman-string:
packages/toc-mode/toc-mode.el:370:2: Warning: docstring wider than 80 characters

In toc--create-tablist-buffer:
packages/toc-mode/toc-mode.el:624:2: Warning: docstring wider than 80 characters

In toc--increase-remaining-and-follow:
packages/toc-mode/toc-mode.el:742:2: Warning: docstring wider than 80 characters

In toc--decrease-remaining-and-follow:
packages/toc-mode/toc-mode.el:748:2: Warning: docstring wider than 80 characters

In toc--add-to-pdf:
packages/toc-mode/toc-mode.el:973:2: Warning: docstring wider than 80 characters

In toc--add-to-djvu:
packages/toc-mode/toc-mode.el:984:2: Warning: docstring wider than 80 characters

In end of data:
packages/toc-mode/toc-mode.el:281:42: Warning: the function ‘pdf-view-active-region-text’ might not be defined at runtime.
packages/toc-mode/toc-mode.el: Warning: the function ‘image-mode-window-get’ might not be defined at runtime.

Re: [ELPA] New package: toc-mode

[dalanicolai]

[-- Attachment #1: Type: text/plain, Size: 2026 bytes --]

It seems that somehow I did not receive the answer by Jean, but the
feedback about the name sounds useful. I will think about and rename
the package.

Actually, I adjusted that copyright line already and got rid of the compiler
warnings, but indeed I see now that I did not push those 'fixes' yet.

On Wed, 21 Sept 2022 at 00:03, Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

> > This package has been for a while on MELPA now, but it would be nice if
> it
> > could be moved to ELPA. The source can be found at
> > https://github.com/dalanicolai/toc-mode.
> >
> > I would like to mention that the PDF functionalities largely depend on
> > pdf-tools, which is not on ELPA of course (doc-view unfortunately does
> > not provide the right features). I am not sure if that somehow is
> > a problem.
>
> Since pdf-tools is in NonGNU ELPA, this is not a problem, no.
>
> > The package description is:
> >
> > Create, cleanup, add and manage Table Of Contents (TOC) of pdf and djvu
> > documents with Emacs
>
> Sounds handy, thanks.  FWIW, I tend to agree with Jean that the name
> suggests its purpose is more general (more like a kind of speedbar/imenu
> maybe).  Furthermore the "-mode" part of the name suggests it's a major
> mode to edit some standard "toc" files rather than an actual tool to
> extract things for non-toc files and then edit those files.
>
> So I'd support a renaming (in case you're out of ideas, maybe
> "toc-edit/edit-doc-toc", tho maybe "create-doc-toc" is more precise
> since it doesn't seem to care very much about editing an existing toc),
> but I don't have a strong opinion about it.
>
> Once you've made up your mind about the package name, let me know so
> I can add it to `elpa.git`.
>
> > ready for ELPA (although I guess it is already ready for publishing on
> > ELPA).
>
> Indeed, except for the copyright line which needs to be adjusted.
>
> The patch below does that along with the obligatory cosmetic tweaks.
> I also include the remaining compilation warnings.
>
>
>         Stefan
>

[-- Attachment #2: Type: text/html, Size: 2713 bytes --]

Re: [ELPA] New package: toc-mode

[dalanicolai]

[-- Attachment #1: Type: text/plain, Size: 2198 bytes --]

Thanks you all for your answers!

On Wed, 21 Sept 2022 at 09:18, dalanicolai <dalanicolai@gmail.com> wrote:

> It seems that somehow I did not receive the answer by Jean, but the
> feedback about the name sounds useful. I will think about and rename
> the package.
>
> Actually, I adjusted that copyright line already and got rid of the
> compiler
> warnings, but indeed I see now that I did not push those 'fixes' yet.
>
> On Wed, 21 Sept 2022 at 00:03, Stefan Monnier <monnier@iro.umontreal.ca>
> wrote:
>
>> > This package has been for a while on MELPA now, but it would be nice if
>> it
>> > could be moved to ELPA. The source can be found at
>> > https://github.com/dalanicolai/toc-mode.
>> >
>> > I would like to mention that the PDF functionalities largely depend on
>> > pdf-tools, which is not on ELPA of course (doc-view unfortunately does
>> > not provide the right features). I am not sure if that somehow is
>> > a problem.
>>
>> Since pdf-tools is in NonGNU ELPA, this is not a problem, no.
>>
>> > The package description is:
>> >
>> > Create, cleanup, add and manage Table Of Contents (TOC) of pdf and djvu
>> > documents with Emacs
>>
>> Sounds handy, thanks.  FWIW, I tend to agree with Jean that the name
>> suggests its purpose is more general (more like a kind of speedbar/imenu
>> maybe).  Furthermore the "-mode" part of the name suggests it's a major
>> mode to edit some standard "toc" files rather than an actual tool to
>> extract things for non-toc files and then edit those files.
>>
>> So I'd support a renaming (in case you're out of ideas, maybe
>> "toc-edit/edit-doc-toc", tho maybe "create-doc-toc" is more precise
>> since it doesn't seem to care very much about editing an existing toc),
>> but I don't have a strong opinion about it.
>>
>> Once you've made up your mind about the package name, let me know so
>> I can add it to `elpa.git`.
>>
>> > ready for ELPA (although I guess it is already ready for publishing on
>> > ELPA).
>>
>> Indeed, except for the copyright line which needs to be adjusted.
>>
>> The patch below does that along with the obligatory cosmetic tweaks.
>> I also include the remaining compilation warnings.
>>
>>
>>         Stefan
>>
>

[-- Attachment #2: Type: text/html, Size: 3123 bytes --]

Re: [ELPA] New package: toc-mode

[Visuwesh]

[செவ்வாய் செப்டம்பர் 20, 2022] dalanicolai wrote:

> This package has been for a while on MELPA now, but it would be nice if it
> could be moved to ELPA. The source can be found at
> https://github.com/dalanicolai/toc-mode.
>
> I would like to mention that the PDF functionalities largely depend on
> pdf-tools, which is not on
> ELPA of course (doc-view unfortunately does not provide the right
> features). I am not sure
> if that somehow is a problem.
>
> [...]

Thanks for this package, it simplified adding TOC to a pdf file
immensely but I had a couple hiccups when using it:

    1. Can we have a command that sets the page number of an outline
       item by reading it from the user?  I.e., if I say M-x
       toc-set-page-number RET 20, it would set the heading's page
       number to 20, and a respective -remaining command.  This would be
       a very nice complement to <right> and S-<right> that we already
       have.  Equivalently, we could also accept a numeric argument for
       <right> and S-<right>.
    2. AFAICT, there is no way to edit the outline level from the
       tabular buffer?  Is this possible, I figured out the way to
       adjust the level is to edit the spaces in the first buffer, but
       that took some trying to figure out.
    3. Finally, can you put the commonly used keybinding in the
       major-mode's documentation?

If you would like to have these as patches instead, then I can try to
shoot some in two weeks time.

Re: [ELPA] New package: toc-mode

[dalanicolai]

[-- Attachment #1: Type: text/plain, Size: 3116 bytes --]

Thanks for the feedback!

However, I am not sure if I understand every point correctly.

For point 1, I would say just keeping (S)-<left/right> pressed works so
fast, that I think
it is not necessary to set the page number by reading from the user (b.t.w.
I think,
generally, C-<left/right> are the most useful keys in tabular-mode). As
mentioned in
the instructions for the tabular mode
<https://github.com/dalanicolai/toc-mode#3-toc-tabular-adjust-pagenumbers>
the contents of every field in tabular mode can be
updated by reading from the user through placing the cursor on the field
and then pressing
C-r. I see now, that the phrasing of that instruction could be a improved.

For point 2, the answer again is that you can press C-r on the field to
update it. However,
the tabular-mode should mainly be used for adjusting the page numbers.
Cleaning up, and
setting levels, should preferably be done in the 'cleanup' stage
<https://github.com/dalanicolai/toc-mode#2-toc-cleanup>.

As far as I know, the most use keybindings are major-mode keybindings, and
automatically
listed when checking the mode documentation using C-h m, as mentioned in
the first section of the usage instructions
<https://github.com/dalanicolai/toc-mode#usage>. Or are you thinking about
something else?

Of course if you see any improvement, then patches are welcome (although I
prefer pull
requests, but all is fine).

On Sun, 25 Sept 2022 at 13:44, Visuwesh <visuweshm@gmail.com> wrote:

> [செவ்வாய் செப்டம்பர் 20, 2022] dalanicolai wrote:
>
> > This package has been for a while on MELPA now, but it would be nice if
> it
> > could be moved to ELPA. The source can be found at
> > https://github.com/dalanicolai/toc-mode.
> >
> > I would like to mention that the PDF functionalities largely depend on
> > pdf-tools, which is not on
> > ELPA of course (doc-view unfortunately does not provide the right
> > features). I am not sure
> > if that somehow is a problem.
> >
> > [...]
>
> Thanks for this package, it simplified adding TOC to a pdf file
> immensely but I had a couple hiccups when using it:
>
>     1. Can we have a command that sets the page number of an outline
>        item by reading it from the user?  I.e., if I say M-x
>        toc-set-page-number RET 20, it would set the heading's page
>        number to 20, and a respective -remaining command.  This would be
>        a very nice complement to <right> and S-<right> that we already
>        have.  Equivalently, we could also accept a numeric argument for
>        <right> and S-<right>.
>     2. AFAICT, there is no way to edit the outline level from the
>        tabular buffer?  Is this possible, I figured out the way to
>        adjust the level is to edit the spaces in the first buffer, but
>        that took some trying to figure out.
>     3. Finally, can you put the commonly used keybinding in the
>        major-mode's documentation?
>
> If you would like to have these as patches instead, then I can try to
> shoot some in two weeks time.
>

[-- Attachment #2: Type: text/html, Size: 3915 bytes --]

Re: [ELPA] New package: toc-mode

[dalanicolai]

[-- Attachment #1: Type: text/plain, Size: 3773 bytes --]

I guess it does no harm to explicitly mention it again here (it is also in
the usage instructions
<https://github.com/dalanicolai/toc-mode#software-generated-pdfs-with-pdftocgen--httpskrasjetcomvoicepdftocgen>
)...

If you have a scanned pdf, then it is strongly recommended to use the
pdf.tocgen <https://pypi.org/project/pdf.tocgen/> functionality.
Using that, then in most cases, you can really extract the TOC and add it
to the document in
a (few) minute(s).

On Sun, 25 Sept 2022 at 18:47, dalanicolai <dalanicolai@gmail.com> wrote:

> Thanks for the feedback!
>
> However, I am not sure if I understand every point correctly.
>
> For point 1, I would say just keeping (S)-<left/right> pressed works so
> fast, that I think
> it is not necessary to set the page number by reading from the user
> (b.t.w. I think,
> generally, C-<left/right> are the most useful keys in tabular-mode). As
> mentioned in
> the instructions for the tabular mode
> <https://github.com/dalanicolai/toc-mode#3-toc-tabular-adjust-pagenumbers>
> the contents of every field in tabular mode can be
> updated by reading from the user through placing the cursor on the field
> and then pressing
> C-r. I see now, that the phrasing of that instruction could be a improved.
>
> For point 2, the answer again is that you can press C-r on the field to
> update it. However,
> the tabular-mode should mainly be used for adjusting the page numbers.
> Cleaning up, and
> setting levels, should preferably be done in the 'cleanup' stage
> <https://github.com/dalanicolai/toc-mode#2-toc-cleanup>.
>
> As far as I know, the most use keybindings are major-mode keybindings, and
> automatically
> listed when checking the mode documentation using C-h m, as mentioned in
> the first section of the usage instructions
> <https://github.com/dalanicolai/toc-mode#usage>. Or are you thinking
> about something else?
>
> Of course if you see any improvement, then patches are welcome (although I
> prefer pull
> requests, but all is fine).
>
> On Sun, 25 Sept 2022 at 13:44, Visuwesh <visuweshm@gmail.com> wrote:
>
>> [செவ்வாய் செப்டம்பர் 20, 2022] dalanicolai wrote:
>>
>> > This package has been for a while on MELPA now, but it would be nice if
>> it
>> > could be moved to ELPA. The source can be found at
>> > https://github.com/dalanicolai/toc-mode.
>> >
>> > I would like to mention that the PDF functionalities largely depend on
>> > pdf-tools, which is not on
>> > ELPA of course (doc-view unfortunately does not provide the right
>> > features). I am not sure
>> > if that somehow is a problem.
>> >
>> > [...]
>>
>> Thanks for this package, it simplified adding TOC to a pdf file
>> immensely but I had a couple hiccups when using it:
>>
>>     1. Can we have a command that sets the page number of an outline
>>        item by reading it from the user?  I.e., if I say M-x
>>        toc-set-page-number RET 20, it would set the heading's page
>>        number to 20, and a respective -remaining command.  This would be
>>        a very nice complement to <right> and S-<right> that we already
>>        have.  Equivalently, we could also accept a numeric argument for
>>        <right> and S-<right>.
>>     2. AFAICT, there is no way to edit the outline level from the
>>        tabular buffer?  Is this possible, I figured out the way to
>>        adjust the level is to edit the spaces in the first buffer, but
>>        that took some trying to figure out.
>>     3. Finally, can you put the commonly used keybinding in the
>>        major-mode's documentation?
>>
>> If you would like to have these as patches instead, then I can try to
>> shoot some in two weeks time.
>>
>

[-- Attachment #2: Type: text/html, Size: 4881 bytes --]

Re: [ELPA] New package: toc-mode

[Yuri Khan]

On Sun, 25 Sept 2022 at 23:49, dalanicolai <dalanicolai@gmail.com> wrote:

> As mentioned in
> the instructions for the tabular mode the contents of every field in tabular mode can be
> updated by reading from the user through placing the cursor on the field and then pressing
> C-r.

Do you seriously rebind C-r away from isearch-backward?

Re: [ELPA] New package: toc-mode

[dalanicolai]

[-- Attachment #1: Type: text/plain, Size: 698 bytes --]

Well, I am an evil (vim keybindings) user, and only know very few Emacs
default keybindings.
Also, I guess search functionality is not very important when simply
adjusting page numbers in a table of contents.

But suggestions for improvements are always welcome.

On Sun, 25 Sept 2022 at 19:13, Yuri Khan <yuri.v.khan@gmail.com> wrote:

> On Sun, 25 Sept 2022 at 23:49, dalanicolai <dalanicolai@gmail.com> wrote:
>
> > As mentioned in
> > the instructions for the tabular mode the contents of every field in
> tabular mode can be
> > updated by reading from the user through placing the cursor on the field
> and then pressing
> > C-r.
>
> Do you seriously rebind C-r away from isearch-backward?
>

[-- Attachment #2: Type: text/html, Size: 1139 bytes --]

Re: [ELPA] New package: toc-mode

[Philip Kaludercic]

dalanicolai <dalanicolai@gmail.com> writes:

> Well, I am an evil (vim keybindings) user, and only know very few Emacs
> default keybindings.
> Also, I guess search functionality is not very important when simply
> adjusting page numbers in a table of contents.

One of the nice things about Emacs is that everything is a buffer and
can be treated as text that you process just like any file or non-file
buffer.  If someone wants to search a buffer, I consider it improper for
a package to inhibit them from doing so.

(I haven't checked, but I am guessing that C-r is supposed to be a
mnemonic for "refresh"?  It would be more conventional to bind this to
"g", that `special-mode' binds to `revert-buffer' -- this also means
that you can just use `revert-buffer-function' directly instead.)

> But suggestions for improvements are always welcome.
>
> On Sun, 25 Sept 2022 at 19:13, Yuri Khan <yuri.v.khan@gmail.com> wrote:
>
>> On Sun, 25 Sept 2022 at 23:49, dalanicolai <dalanicolai@gmail.com> wrote:
>>
>> > As mentioned in
>> > the instructions for the tabular mode the contents of every field in
>> tabular mode can be
>> > updated by reading from the user through placing the cursor on the field
>> and then pressing
>> > C-r.
>>
>> Do you seriously rebind C-r away from isearch-backward?
>>

Re: [ELPA] New package: toc-mode

[dalanicolai]

[-- Attachment #1: Type: text/plain, Size: 1747 bytes --]

I have changed the binding to just `r' then.

I don't remember why I chose `r`, but I guess it stands for 'replace'.
As I am using evil, I prefer if the same bindings also work in evil,
without further configuration. However, `r` works perfectly fine for
both here, so it looks as a perfect alternative.

On Sun, 25 Sept 2022 at 23:37, Philip Kaludercic <philipk@posteo.net> wrote:

> dalanicolai <dalanicolai@gmail.com> writes:
>
> > Well, I am an evil (vim keybindings) user, and only know very few Emacs
> > default keybindings.
> > Also, I guess search functionality is not very important when simply
> > adjusting page numbers in a table of contents.
>
> One of the nice things about Emacs is that everything is a buffer and
> can be treated as text that you process just like any file or non-file
> buffer.  If someone wants to search a buffer, I consider it improper for
> a package to inhibit them from doing so.
>
> (I haven't checked, but I am guessing that C-r is supposed to be a
> mnemonic for "refresh"?  It would be more conventional to bind this to
> "g", that `special-mode' binds to `revert-buffer' -- this also means
> that you can just use `revert-buffer-function' directly instead.)
>
> > But suggestions for improvements are always welcome.
> >
> > On Sun, 25 Sept 2022 at 19:13, Yuri Khan <yuri.v.khan@gmail.com> wrote:
> >
> >> On Sun, 25 Sept 2022 at 23:49, dalanicolai <dalanicolai@gmail.com>
> wrote:
> >>
> >> > As mentioned in
> >> > the instructions for the tabular mode the contents of every field in
> >> tabular mode can be
> >> > updated by reading from the user through placing the cursor on the
> field
> >> and then pressing
> >> > C-r.
> >>
> >> Do you seriously rebind C-r away from isearch-backward?
> >>
>

[-- Attachment #2: Type: text/html, Size: 2539 bytes --]

Re: [ELPA] New package: toc-mode

[Visuwesh]

[ஞாயிறு செப்டம்பர் 25, 2022] dalanicolai wrote:

> Thanks for the feedback!

Thank you for your answers!

> However, I am not sure if I understand every point correctly.
>
> For point 1, I would say just keeping (S)-<left/right> pressed works so
> fast, that I think
> it is not necessary to set the page number by reading from the user 

Having to hold S-<left/right> till the number increases by 20 is not
fast enough, unfortunately.

> As mentioned in the instructions for the tabular mode
> <https://github.com/dalanicolai/toc-mode#3-toc-tabular-adjust-pagenumbers>
> the contents of every field in tabular mode can be updated by reading
> from the user through placing the cursor on the field and then
> pressing C-r. I see now, that the phrasing of that instruction could
> be a improved.

I completely missed C-r since it wasn't mentioned in the Commentary
section, nor does the command have a docstring.  🙃

> For point 2, the answer again is that you can press C-r on the field to
> update it.

I see now, thanks.

> However, the tabular-mode should mainly be used for adjusting the page
> numbers.  Cleaning up, and setting levels, should preferably be done
> in the 'cleanup' stage
> <https://github.com/dalanicolai/toc-mode#2-toc-cleanup>.

I figured it out but it took me some time to find out that whitespace
governs the outline level.  Maybe I missed the explanation in the
Commentary since I skimmed it due to being in a hurry (my mistake!).

> As far as I know, the most use keybindings are major-mode keybindings, and
> automatically
> listed when checking the mode documentation using C-h m, as mentioned in
> the first section of the usage instructions
> <https://github.com/dalanicolai/toc-mode#usage>. Or are you thinking about
> something else?

I was thinking we could put the keybinding texts from the Commentary in
the major-mode docstrings since it is hard to fish through all the
bindings and find the toc-mode ones.

    ;; toc-mode (tablist)
    ;; TAB~               preview/jump-to-page
    ;; right/left         toc-in/decrease-remaining
    ;; C-right/C-left     toc-in/decrease-remaining and view page
    ;; S-right/S-left     in/decrease pagenumber current entry
    ;; C-down/C-up        scroll document other window (if document buffer shown)
    ;; S-down/S-up        full page scroll document other window ( idem )
    ;; C-j                toc--jump-to-next-entry-by-level

[ Here, the Commentary section and the README file are out-of-sync.  I
  tried `C-x v +' but it didn't pull any new changes, you might want to
  check this.  ]
  
> Of course if you see any improvement, then patches are welcome (although I
> prefer pull
> requests, but all is fine).

Sure, I will make a pull request.