Enable use of the org-citation locator for a direct go to page citar-dwim command.

[MirkoHernandez]

Is your feature request related to a problem? Please describe.
Usually when opening a file using citar-dwim I then have to move to the specific page in a separate additional step.

[cite:@foundation21:_guile_refer_manual]  Here is the page number =84=

I store the page number near the org citation. I open the document using citar-dwim ( if it is not already open) and then I call a goto-page or goto-timestamp command that uses the number string to set the appropriate page or timestamp.

Describe the solution you'd like
I would like to use the org-citation for this exact purpose. Calling citar-dwim or a similar command could make use of the citation locator suffix, and call the referencing command directly.

[cite:@foundation21:_guile_refer_manual pp. 84]   Calling citar-dwim opens the document in page 84.

Describe alternatives you've considered
org-noter is a package that stores and can refer to the page number information, but it is not as flexible as org citations, which can be used anywhere. Some of the disadvantages of org-noter.

• A file path must be specified of where the document is.
• A header is required to indicate each page number .
• Those requirements enforce a specific document structure

I'm not familiar with any other package similar to org-noter but I guess that using the locator suffix of an org-citation could provide the most important features of that package.

Alternatively two commands could be provided for programmatic use: one that returns the file path related to a citekey, and another that extracts the locator suffix.

[bdarcus]

Interesting idea, but I can't see it working, at least as a general matter, mostly because ...

... using the locator suffix of an org-citation could provide the most important features of that package.

In my experience, the page you cite is not the same as a PDF page, which I suppose is why org-noter has the complicated solution?

Alternatively two commands could be provided for programmatic use: one that returns the file path related to a citekey ...

For this, can you not just use citar-get-files and grab the base directory of the file you want?

[MirkoHernandez]

In my experience, the page you cite is not the same as a PDF page, which I suppose is why org-noter has the complicated solution?

The command pdf-view-goto-page (from the pdf-tools package ) can be used for this purpose, but I understand that citar is probably not design for interfacing with a particular program, and maybe my request to extend citar-dwim is out of citar's scope.

For this, can you not just use citar-get-files and grab the base directory of the file you want?

Yes this is very useful, I think that this combined with a function that extracts the suffix is all that would be required for creating custom goto commands. Maybe this is more related to the design of citar and a function like that could be provided for programmatic use.

I'm trying to create a simple version of that function, but it does not work. The following returns an object that is supposed to be of type string but it does not behave as a regular string. Could you help me with this?

(defun my/get-suffix-from-citation (citation)
  (car 
   (plist-get (car 
	       (alist-get 'citation-reference
			  (alist-get 'citation (org-cite-parse-objects citation)))) 
	      :suffix)))

(type-of (my/get-suffix-from-citation "[cite:@foundation21:_guile_refer_manual pp.  95]"))  ;; string?

[bdarcus]

The command pdf-view-goto-page (from the pdf-tools package ) can be used for this purpose, but I understand that citar is probably not design for interfacing with a particular program, and maybe my request to extend citar-dwim is out of citar's scope.

Really what you're asking for is to extend the citar open-at-point functionality to be able to include the locators for opening in pdf-tools.

That goes beyond citar-dwim then, and should ideally work with embark-act, any hypothetical transient or hydra menu, etc.

But as you notice, the challenge is it's specific to pdf-tools, and I'm not sure what that means given the current codebase, including:

• the functions in general
• especially our "major-mode functions", since in theory this should also work in markdown and LaTeX, at least at some point
• how we do configuration; see citar-major-mode-functions and citar-file-open-functions (the latter is where one could have to specify pdf-view-goto-page, but that then requires arguments, while now the config value is just a function symbol)

Per below, perhaps you can try to figure this out, and at minimum, we can include it in the wiki, which is where I like to put developing ideas that may or may not be appropriate for citar proper.

I could imagine once sufficiently developed, we could consider adding a small citar-pdf-tools package.

Could you help me with this?

Try this?

(defun my/org-suffix-at-point ()
  (when-let ((reference
              (citar-org--reference-at-point (org-element-context))))
    (substring-no-properties
     (car (org-element-property :suffix reference)))))

It might be worth including a function like this, because we could maybe use it for other things.

But for now, if you get this working, could you add a wiki subsection here?

https://github.com/emacs-citar/citar/wiki/Example-functions#pdf-tools-integration

Aside: I may make that a page dedicated to pdf-tools!

[MirkoHernandez]

Thanks! the substring-no-properties function worked perfectly but I did not find citar-org--reference-at-point , it does not matter, the suffix can be extracted. I will adapt the current goto page function that I have and post it here when it is finished (can't do it at the moment).

But for now, if you get this working, could you add a wiki subsection here?
https://github.com/emacs-citar/citar/wiki/Example-functions#pdf-tools-integration

Yes, I will. I have a similar emms function and maybe that could be posted too but I'm not sure yet of what kind of citation locator should be used for timestamps.

[MirkoHernandez]

I did not considered it previously but I had an outdated citar package I upgraded and now I have citar-org--reference-at-point working properly, so thanks again. Using that function the suffix can be obtained and this is pretty much what is needed to create a go to page command (my use case is to have two buffers open, one displaying the pdf so I guess that the following code would not work very well if three or more buffers are open).

(defun my/org-suffix-at-point ()
 "Return the suffix associated with an org citation at point." 
 (interactive) 
  (when-let* ((reference  (citar-org--reference-at-point (org-element-context)))
              (suffix (car (org-element-property :suffix reference))))
	      (when suffix
		(substring-no-properties suffix))))

(defun my/org-citation-suffix-extract-page (s)
  "S is a string representing the suffix of an org citation.
 Return a string  representing the page number  associated with a
 page locator (if a page range is used return only the first page)."
  (when (and s (string-match " +\\(p\\|p\.\\|pp\.\\) +\\([[:digit:]-]+\\)" s))
      (let ((match (match-string 2 s)))
	(when match
	     (car (string-split match "-"))))))

(defun my/org-citation-goto-page ()
 "Find an org-citation, if there is a file corresponding with  the
citekey open that file. If there is a page locator in the citation go to that page using pdf-tools.
Even if the citekey has no associated file, if the other window has `pdf-view-mode' active go to the page indicated by the locator."
  (interactive)
  (search-forward-regexp "\\[cite:@" nil t)
  (let* ((suffix (my/org-suffix-at-point))
	 (key  (org-element-property :key (citar-org--reference-at-point (org-element-context))))
	 (file (and key (car (gethash key (citar-get-files key )))))
	 (page (my/org-citation-suffix-extract-page suffix))
	 (other-w (if (one-window-p) (progn (split-window-right) (other-window-for-scrolling)) (other-window-for-scrolling))))
    (with-selected-window other-w
	  (when file
	    (find-file file))
	  (when (and page (equal major-mode 'pdf-view-mode))
		     (pdf-view-goto-page (string-to-number page))))))

Per below, perhaps you can try to figure this out, and at minimum, we can include it in the wiki, which is where I like to put developing ideas that may or may not be appropriate for citar proper.

In regard to some other file formats maybe an heuristic could be derived from the height of a buffer in terms of lines, and the latex or markdown exporting configuration, the result may not as precise but it could be somewhat useful (I'm not using those file formats at the moment so I wouldn't know how to approach this). I agree that those issues are probably not directly related to citar but providing access to the suffix enables the possibility to try things out.

[bdarcus]

Oh yeah, you were pretty out of date on citar! On markdown and latex, you need to look at what I pointed you to; I mean them as authoring formats, where the citations have locators.

[bdarcus]

Did you see this org-noter news?

https://www.reddit.com/r/emacs/comments/11x237p/orgnoter_is_under_new_maintainership_with_the/

Also, based on this, I created another issue:

#756

PS - should we close this?

[MirkoHernandez]

Regarding the citar-org--reference-at-point function, It turns out that It was not a version issue, I had to require citar-org in order to have access to that function, I don't think that I need to require citar so this was unexpected. Should I include it in the function? or is it better to require it globally ?.

(defun my/org-citation-goto-page ()
  (interactive)
  (require 'citar-org)
;; rest of the function

Did you see this org-noter news?

I'm not currently using that package but I will probably try out any new developments. Thanks I will check it.

PS - should we close this?

Yes, your code sample was just what I needed, thanks you. I did not edit any wiki page since I was not sure how this feature request is related to citar proper. Should I post the sample code as it stands?