few fixes and docu updates for rdoc and pydoc macros

mittelmark · Sep 28, 2024 · 788ea37 · 788ea37
1 parent d515a27
commit 788ea37
Show file tree

Hide file tree

Showing 7 changed files with 263 additions and 154 deletions.
diff --git 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
@@ -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
@@ -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,14 +43428,15 @@ $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
   the user via the command line.
 
 ## EXAMPLE
 
-       pydoc "argparse"
+       pydoc "argparse"  
        pydoc "sys"
 
 ## NOTES

diff --git 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 <RETURN> key
+        buffer-bind-create "bio" "return" "0" r-doc-process-link
+        ; Move between links with the <TAB> 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 &not &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 &not $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
@@ -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,14 +42848,15 @@ $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
     the user via the command line.
 
 cEEXAMPLE cA
 
-         pydoc "argparse"
+         pydoc "argparse"  
          pydoc "sys"
 
 cENOTES cA

diff --git 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