From 788ea372236e2dc668aca24c91a973b7c712c891 Mon Sep 17 00:00:00 2001 From: Detlef Groth Date: Sat, 28 Sep 2024 05:21:06 +0200 Subject: [PATCH] few fixes and docu updates for rdoc and pydoc macros --- ChangeLog | 6 +- doc/files.txt | 1 + doc/me.smd | 28 ++++-- jasspa/macros/hkrdoc.emf | 151 +++-------------------------- jasspa/macros/me.ehf | 29 ++++-- jasspa/macros/me.emf | 2 +- jasspa/macros/rdoc.emf | 200 +++++++++++++++++++++++++++++++++++++++ 7 files changed, 263 insertions(+), 154 deletions(-) create mode 100644 jasspa/macros/rdoc.emf diff --git a/ChangeLog b/ChangeLog index f65b6ca..68966f7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -7,12 +7,16 @@ > > Created By : Jon Green > Created : Fri Feb 6 11:13:34 2004 -> Last Modified : <240922.0632> +> Last Modified : <240928.0451> > Authors: : John Green, Steven Phillips, Detlef Groth [240927] - support for Markdown as define-help language + - adding rdoc(3) command + - adding r(9) documentation + - adding !hm and !he abbreviations for macro help + - adding pydoc(3) command [240920] diff --git a/doc/files.txt b/doc/files.txt index 8ee4bab..773a4f3 100644 --- a/doc/files.txt +++ b/doc/files.txt @@ -666,6 +666,7 @@ m3mac096.html git-status(3) m3mac097.html save-kbd-macro(3) m3mac098.html xrdb-scheme(3) m3mac099.html rdoc(3) +m3mac100.html pydoc(3) m3osd000.html user-setup(3) m3osd001.html organizer(3) m3osd002.html find-word(3) diff --git a/doc/me.smd b/doc/me.smd index 9b3e835..746fbcc 100644 --- a/doc/me.smd +++ b/doc/me.smd @@ -4982,6 +4982,10 @@ - [20240927] - support for Markdown as define-help language + - adding [rdoc(3)](rdoc(3)) command + - adding [r(9)](r(9)) documentation + - adding !hm and !he abbreviations for macro help + - adding [pydoc(3)](pydoc(3)) command - [240920] - documenting save-kbd-macro(3) @@ -43383,16 +43387,27 @@ $a Displays in a hypertext browser with R syntax hilighting the manual pages for R packages or R functions. + You can fold or unfold the section and use the [item-list(3)](item-list(3)) + command to navigate the documentation sections. If no argment is given + requests a package or function name from the user via the command line. + Package overview pages should be requested using the syntax + "package::pkgname", documentation for specific functions should be requested + using the syntax "pkgname::funcname". Links to other functions and to the + main package overview are shown with hilights in the normal text. Usage and + Examples sections use R highlighting. ## EXAMPLE - - rdoc "plot" - rdoc "cluster::pam" - rdoc "package::cluster" + +```{.emf} + rdoc ; requests a help page from the user + rdoc "plot" ; function documentation + rdoc "cluster::pam" ; function pam in package cluster + rdoc "package::cluster" ; package overview with functions +``` ## NOTES - __rdoc__ macro is defined in file `hkrdoc.emf`. + __rdoc__ macro is defined in file `hkrdoc.emf`. ## SEE ALSO @@ -43413,6 +43428,7 @@ $a ## DESCRIPTION Displays with the manual page for a Python package module or package. + You can fold or unfold the section and use the [item-list(3)](item-list(3)) command to get an overview about section and classes in a module or package. If no argment is given requests a package or function name from @@ -43420,7 +43436,7 @@ $a ## EXAMPLE - pydoc "argparse" + pydoc "argparse" pydoc "sys" ## NOTES diff --git a/jasspa/macros/hkrdoc.emf b/jasspa/macros/hkrdoc.emf index 276c9dd..2eec460 100644 --- a/jasspa/macros/hkrdoc.emf +++ b/jasspa/macros/hkrdoc.emf @@ -3,7 +3,7 @@ ; Author : $Author$ ; Created By : Detlef Groth ; Created : Thu Sep 26 14:43:10 2024 -; Last Modified : <240926.1642> +; Last Modified : <240926.1936> ; ; Description ; @@ -15,8 +15,16 @@ ; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; define-macro fhook-rdoc - @# buffer-init "rdoc" - buffer-init-hooks + @# buffer-init "rdoc" + !if &seq $buffer-bname "*rdoc*" + ; Hyperlink with the key + buffer-bind-create "bio" "return" "0" r-doc-process-link + ; Move between links with the key + buffer-bind-create "bio" "tab" "" r-doc-forward-link + buffer-bind-create "bio" "S-tab" "" r-doc-backward-link + buffer-bind-create "bio" "space" "" scroll-down + !endif + buffer-init-hooks !emacro ; buffer-init variables @@ -30,7 +38,7 @@ set-variable .fhook-rdoc.setup-mask "acfhmw" 0 hilight .hilight.rdoc 0 .scheme.text !iif ¬ &exi ".hilight.r" !force execute-file "hkr" hilight .hilight.rdoc 0xc0 "^cEUsage:cA" "Usage:" .hilight.r .scheme.header - hilight .hilight.rdoc 0xc0 "^cEExamples:cA" "Example:" .hilight.r .scheme.header + hilight .hilight.rdoc 0xc0 "^cEExamples:cA" "Examples:" .hilight.r .scheme.header hilight .hilight.r 0xc0 "cE(.+)cA" "\\1" .hilight.rdoc .scheme.header hilight .hilight.r 0x44 "^cE" "" "cA" "" "" .scheme.header hilight .hilight.rdoc 0x44 "^cE" "" "cA" "" "" .scheme.header @@ -48,140 +56,5 @@ set-variable .fhook-rdoc.setup-mask "acfhmw" set-variable .fhook-rdoc.item-list-s1 "^\ecE\\([A-Z].+\\)\ecA" set-variable .fhook-rdoc.item-list-r1 "SECT \ecB\\1\ecA" -add-file-hook "*rdoc*" fhook-rdoc - -define-macro rdoc - !force set-variable #l0 @1 - !if ¬ $status - set-variable #l0 @ml00 "R help on" - !endif - !if &seq #l0 "" - !return - !endif - set-variable #l0 &rep #l0 "::" ":" - !if &xse #l0 "\\(.+\\):\\(.+\\)" - !if &or &seq @s1 "library" &seq @s1 "package" - set-variable #l1 &spr "options(useFancyQuotes = FALSE);library(help='%s')" @s2 - set-variable .package @s2 - !else - set-variable #l1 &spr "options(useFancyQuotes = FALSE);help('%s',package='%s',help_type='text')" @s2 @s1 - set-variable .package @s1 - !endif - !else - ; options(useFancyQuotes = FALSE); - set-variable .package "" - set-variable #l1 &spr "options(useFancyQuotes = FALSE);help('%s')" #l0 - !endif - 0 pipe-shell-command &spr "LANG=en_US Rscript -e \"%s\"" #l1 "*rdoc*" - set-variable :mouse-word-select r-doc-process-link - -1 buffer-mode "view" - beginning-of-buffer - ;set-variable $debug 2 - !force search-buffer "me" "During startup - Warning messages:" - !if $status - beginning-of-line - 1 kill-line - !endif - !force search-buffer "me" "Setting LC_.+ failed" - !while $status - beginning-of-line - 1 kill-line - !force search-buffer "me" "Setting LC_.+ failed" - !done - beginning-of-buffer - 3 kill-line - replace-string "_" "" - beginning-of-buffer - replace-string "^See Also:" "\ecESee Also:\ecA" - beginning-of-buffer - replace-string "^\\(\\u\\l[^ :]+:\\)$" "\ecE\\1\ecA" - beginning-of-buffer - replace-string " \\(package:[^ ]+\\) " " \els\\1\ele " - beginning-of-buffer - !force search-buffer "me" "^\\ecESee Also:" - !if $status - 2 forward-line - ;set-variable $debug 2 - beginning-of-line - set-variable #l1 0 - ; maximal 5 lines as &xse has problems with while - !while &less #l1 6 - ; &xse @wl "^\\S" does not work ... - -1 replace-string "'\\([^']+\\)'" "\els\\1\ele" - forward-line - beginning-of-line - set-variable #l1 &add #l1 1 - !done - !endif - beginning-of-buffer - ;; package documentation with Index: - !force search-buffer "me" "^\\ecEIndex:" - !if $status - 2 forward-line - beginning-of-line - set-variable #l1 0 - ; maximal 5 lines - !while &less #l1 100 - ; &xse @wl "^\\S" does not work ... - -1 replace-string "^\\([^\\s]+\\)" "\els\\1\ele" - !force forward-line - !if $status - beginning-of-line - !endif - set-variable #l1 &add #l1 1 - !done - beginning-of-buffer - !endif - ;execute-file "hkrdoc" - beginning-of-buffer - 1 buffer-mode "view" - !if &band $system 0x01 - ; some terminals might need this - screen-update - !endif - -!emacro - -0 define-macro r-doc-process-link - ;set-variable $debug 3 - set-position "\x80" - set-variable #l0 $window-col - set-variable #l1 $window-line - ;set-variable $debug 2 - !force -2 search-forward "\ele" - !if $status - set-variable #l2 $window-col - set-variable #l3 $window-line - 3 backward-char - !force -2 search-backward "\els" - !if $status - set-variable #l4 $window-col - set-variable #l5 $window-line - 3 forward-char - ; all on same line? and - !if &and &equ #l1 #l3 &equ #l3 #l5 - !if &and &less #l0 #l2 &great #l0 #l4 - set-mark - search-forward "\ele" - 3 backward-char - copy-region - set-variable #l6 @y - -1 yank - ;3000 ml-write &spr "fetching %s" #l6 - !if &seq .rdoc.package "" - rdoc #l6 - !else - !if &equ &sin "package:" #l6 0 - rdoc &spr "%s::%s" .rdoc.package #l6 - !else - ; click on package:pkgname - rdoc #l6 - !endif - !endif - !endif - !endif - !endif - !endif -!emacro 1000 ml-write "load new hkrdoc" diff --git a/jasspa/macros/me.ehf b/jasspa/macros/me.ehf index 81dff5c..fa13193 100644 --- a/jasspa/macros/me.ehf +++ b/jasspa/macros/me.ehf @@ -5057,6 +5057,10 @@ Miscellaneous Information - [20240927] - support for Markdown as define-help language + - adding lsrdoc(3)lmrdoc(3)le command + - adding lsr(9)lmr(9)le documentation + - adding !hm and !he abbreviations for macro help + - adding lspydoc(3)lmpydoc(3)le command - [240920] - documenting save-kbd-macro(3) @@ -42805,16 +42809,26 @@ $a Displays in a hypertext browser with R syntax hilighting the manual pages for R packages or R functions. + You can fold or unfold the section and use the lsitem-list(3)lmitem-list(3)le + command to navigate the documentation sections. If no argment is given + requests a package or function name from the user via the command line. + Package overview pages should be requested using the syntax + "package::pkgname", documentation for specific functions should be requested + using the syntax "pkgname::funcname". Links to other functions and to the + main package overview are shown with hilights in the normal text. Usage and + Examples sections use R highlighting. cEEXAMPLE cA - - rdoc "plot" - rdoc "cluster::pam" - rdoc "package::cluster" - + +sB + rdoc ; requests a help page from the user + rdoc "plot" ; function documentation + rdoc "cluster::pam" ; function pam in package cluster + rdoc "package::cluster" ; package overview with functions +sA cENOTES cA - cDrdoccA macro is defined in file cGhkrdoc.emfcA. + cDrdoccA macro is defined in file cGhkrdoc.emfcA. cESEE ALSO cA @@ -42834,6 +42848,7 @@ $a cEDESCRIPTION cA Displays with the manual page for a Python package module or package. + You can fold or unfold the section and use the lsitem-list(3)lmitem-list(3)le command to get an overview about section and classes in a module or package. If no argment is given requests a package or function name from @@ -42841,7 +42856,7 @@ $a cEEXAMPLE cA - pydoc "argparse" + pydoc "argparse" pydoc "sys" cENOTES cA diff --git a/jasspa/macros/me.emf b/jasspa/macros/me.emf index 3315906..9ffd324 100644 --- a/jasspa/macros/me.emf +++ b/jasspa/macros/me.emf @@ -71,7 +71,7 @@ define-macro-file mail mail mail-check stop-mail-check define-macro-file fileopen osd-file-open osd-get-file define-macro-file spellaut auto-spell auto-spell-menu define-macro-file hkinfo info info-on info-goto-link -define-macro-file hkrdoc rdoc +define-macro-file rdoc rdoc define-macro-file hkpydoc pydoc define-macro-file zfile find-zfile zfile-setup define-macro-file gentags generate-tags-file diff --git a/jasspa/macros/rdoc.emf b/jasspa/macros/rdoc.emf new file mode 100644 index 0000000..ae51542 --- /dev/null +++ b/jasspa/macros/rdoc.emf @@ -0,0 +1,200 @@ +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +; +; Author : $Author$ +; Created By : Detlef Groth +; Created : Thu Sep 26 19:12:38 2024 +; Last Modified : <240928.0506> +; +; Description +; +; Notes +; +; History +; +; Copyright (c) 2024 Detlef Groth. +; +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +define-macro rdoc + !force set-variable #l0 @1 + !if ¬ $status + set-variable #l0 @ml00 "R help on" + !endif + !if &seq #l0 "" + !return + !endif + set-variable #l0 &rep #l0 "::" ":" + !if &xse #l0 "\\(.+\\):\\(.+\\)" + !if &or &seq @s1 "library" &seq @s1 "package" + set-variable #l1 &spr "options(useFancyQuotes = FALSE);library(help='%s')" @s2 + set-variable .package @s2 + !else + set-variable #l1 &spr "options(useFancyQuotes = FALSE);help('%s',package='%s',help_type='text')" @s2 @s1 + set-variable .package @s1 + !endif + !else + ; options(useFancyQuotes = FALSE); + set-variable .package "" + set-variable #l1 &spr "options(useFancyQuotes = FALSE);help('%s')" #l0 + !endif + r-doc-test #l1 + 1000 ml-write .docu + 0 pipe-shell-command &spr "LANG=en_US Rscript -e \"%s\"" #l1 "*rdoc*" + set-variable :mouse-word-select r-doc-process-link + -1 buffer-mode "view" + beginning-of-buffer + ;set-variable $debug 2 + !force search-buffer "me" "During startup - Warning messages:" + !if $status + beginning-of-line + 1 kill-line + !endif + !force search-buffer "me" "Setting LC_.+ failed" + !while $status + beginning-of-line + 1 kill-line + !force search-buffer "me" "Setting LC_.+ failed" + !done + beginning-of-buffer + 3 kill-line + replace-string "_" "" + beginning-of-buffer + replace-string "^See Also:" "\ecESee Also:\ecA" + beginning-of-buffer + replace-string "^\\(\\u\\l[^ :]+:\\)$" "\ecE\\1\ecA" + beginning-of-buffer + replace-string " \\(package:[^ ]+\\) " " \els\\1\ele " + beginning-of-buffer + !force search-buffer "me" "^\\ecESee Also:" + !if $status + 2 forward-line + ;set-variable $debug 2 + beginning-of-line + set-variable #l1 0 + ; maximal 5 lines as &xse has problems with while + !while &less #l1 6 + ; &xse @wl "^\\S" does not work ... + -1 replace-string "'\\([^']+\\)'" "\els\\1\ele" + forward-line + beginning-of-line + set-variable #l1 &add #l1 1 + !done + !endif + beginning-of-buffer + ;; package documentation with Index: + !force search-buffer "me" "^\\ecEIndex:" + !if $status + 2 forward-line + beginning-of-line + set-variable #l1 0 + ; maximal 5 lines + !while &less #l1 100 + ; &xse @wl "^\\S" does not work ... + -1 replace-string "^\\([^\\s]+\\)" "\els\\1\ele" + !force forward-line + !if $status + beginning-of-line + !endif + set-variable #l1 &add #l1 1 + !done + beginning-of-buffer + !endif + ;execute-file "hkrdoc" + beginning-of-buffer + 1 buffer-mode "view" + !if &band $system 0x01 + ; some terminals might need this + screen-update + !endif + +!emacro +define-macro r-doc-test + 0 pipe-shell-command &spr "LANG=en_US Rscript -e \"%s\"" @1 "*tmp*" + find-buffer "*tmp*" + !force search-forward "No documentation for" + !if $status + set-variable .rdoc.docu &spr "No documentation for %s" @1 + delete-buffer "*tmp*" + !return + !endif + !force search-forward "there is no package called" + !if $status + set-variable .rdoc.docu &spr "Not such a package %s" @1 + delete-buffer "*tmp*" + !return + !endif + set-variable .rdoc.docu "OK" + delete-buffer "*tmp*" +!emacro +0 define-macro r-doc-process-link + ;set-variable $debug 3 + set-position "\x80" + set-variable #l0 $window-col + set-variable #l1 $window-line + ;set-variable $debug 2 + !force -2 search-forward "\ele" + !if $status + set-variable #l2 $window-col + set-variable #l3 $window-line + 3 backward-char + !force -2 search-backward "\els" + !if $status + set-variable #l4 $window-col + set-variable #l5 $window-line + 3 forward-char + ; all on same line? and + !if &and &equ #l1 #l3 &equ #l3 #l5 + !if &and &less #l0 #l2 &great #l0 #l4 + set-mark + search-forward "\ele" + 3 backward-char + copy-region + set-variable #l6 @y + -1 yank + ;3000 ml-write &spr "fetching %s" #l6 + !if &seq .rdoc.package "" + rdoc #l6 + !else + !if &equ &sin "package:" #l6 0 + rdoc &spr "%s::%s" .rdoc.package #l6 + !else + ; click on package:pkgname + rdoc #l6 + !endif + !endif + !endif + !endif + !endif + !endif +!emacro +; Advance to the next link in the forward direction +0 define-macro r-doc-forward-link + !if &les @# 0 + set-variable #l0 &sub 0 @# + #l0 r-doc-backward-link + !endif + !force @# search-forward "\els" + !if ¬ $status + ; Not found, force wrap, search and finish + beginning-of-buffer + search-forward "\els" + !endif +!emacro + +; Advance to the next link in the backward direction +0 define-macro r-doc-backward-link + !if &les @# 0 + set-variable #l0 &sub 0 @# + #l0 r-doc-forward-link + !endif + ; move back 3 chars so if we are currently on a link we do move + !force 3 backward-char + !force @# search-backward "\els" + !if ¬ $status + ; Not found, force wrap, search and finish + end-of-buffer + search-backward "\els" + !endif + ; move to the end of the \elm so the user can sensibly move forward + ; and so that subsequent forw/back-link moves work as expected. + 2 show-region +!emacro