README.groff_mode

                                 DESCRIPTION:


groff_mode for the Jed editor is an extension editing mode that facilitates
the editing of groff/nroff/troff files. It has a color highlighting scheme,
but it also has a few other features, such as the toggling of inline markup
styles, previewing of the file in a pdf-viewer as well as being able to
convert and install OpenType or TrueType fonts in a chosen user directory
for use with groff. The mode will auto detect what options to groff that are
needed to convert the current document for a chosen output device.


                                  DOWNLOAD:


It is easiest just to check out my repository on Github, it is only a few
kilobytes:

  git clone https://github.com/mortenivar/Jed-modes.git


                       INSTALLATION and CUSTOMIZATION:


Copy groff_mode.sl to directory in your jed library path, e.g.
/usr/share/jed/lib. If you only have write access to your own home
directory, then do something like this:


  cd
  mkdir -p .jed/lib
  cp groff_mode.sl .jed/lib


and add the following line near the top of your ˝/.jedrc:


  set_jed_library_path(get_jed_library_path () + "," + dircat(getenv("HOME"), ".jed/lib"));


This would include the ".jed/lib" directory under your home directory as
part of the editor's search path for library files.

Also add the following lines to your ~/.jedrc:


   autoload("groff_mode", "groff_mode");
   variable groff_exts = "1 2 3 4 5 6 7 8 man mm ms me mdoc mom nroff troff groff tr trf";
   array_map(Void_Type, &add_mode_for_extension, "groff", strtok(groff_exts));


This enables autoloading of the mode for a number of different file
extensions.

Another way to load the mode is <alt>-x -> groff_mode

You may also add the following block of variables to your ~/.jedrc:


   variable Groff_Output_Device = pdf;
   variable Groff_Pdf_Viewer = "zathura";
   variable Groff_Paper_Format = "A4";
   variable Groff_Encoding = "utf-8";
   variable Groff_Cmd = "";


These settings are the default settings and you may then change them there
to your liking. The variable, "Groff_Cmd", may be used to set a default
groff command line for converting the document in case you have some special
needs or the auto detection for some reason fails. It will then override the
auto detection mechanism.

The variables, "Groff_Output_Device", "Groff_Paper_Format", "Groff_Encoding"
and "Groff_Cmd", may also be changed on the fly from within the editor.


                              INSTALLING FONTS;
            
The mode has an interface for installing groff font description files for
truetype and opentype fonts. It is fine for most needs. However, if you
desire access to the full spectrum of special glyphs that e.g. many of
"nerd" font families contain, then the perl script, "ttffontinstall.pl" is a
much better choice. It is not part of groff yet, but may be downloaded from
https://savannah.gnu.org/bugs/?67700

You may then search for and insert special glyphs like emojis, etc
with "<ctrl>-c G" or with "Insert Glyph" from the menu.


                                   USAGE:


   (e.g. "<ctrl>-cf" means, type <ctrl>-c, release both keys and type 'f')


- <F10> ->  Mode, will show some menu items of available commands.

- <F1>      Search for macro in current line in the manual page for the macro
            package in active use. If there is no macro/request in the
            current line, a free form search expression in a groff manual
            page of choice may be entered from a prompt. If text is marked,
            that text will become the search expression.
            
- <F2>      Free form search in a groff manual page of choice like with
            with <F1> in a line with no macro/request in it.

- <F9>      renders the current buffer in a pdf-viewer, a pager program such
            as less(1) or a browser such as lynx(1). You may keep the
            rendered document open in the pdf-viewer and <F9> will update
            the contents in the pdf-viewer with no need to save the file in
            between or to restart the pdf-viewer. Updating happens
            completely transparently. The status line will be dynamically
            updated with the detected groff options needed to convert the
            document

- <ctrl>-cf will convert and install a TrueType or OpenType font for use
            with groff. It uses the environment variable, $GROFF_FONT_PATH,
            as the installation target. If you have haven't set this
            variable in your environment, it will be set by the mode to
            $XDG_DATA_HOME/groff/site-font. $XDG_DATA_HOME usually defaults
            to $HOME/.local/share. If $XDG_DATA_HOME is not set in your
            environment, the mode will set $GROFF_FONT_PATH to
            $HOME/.local/share/groff/site-font.

- <ctrl>-cF will batch convert and install, either all TrueType or OpenType
            fonts in a directory or a subset of those that match an
            expression. During installation, no user interaction is
            required; the style suffixes, R, B, I, BI, are parsed from the
            font file names and added automatically to the groff font
            description file name.

- <ctrl>-cn will pop up a window with a list of the installed groff font
            description files from which you may insert a chosen font name
            into the buffer. The names may be completed with the <tab> key.

- <ctrl>-ci will apply some text attribute to the current word or a block of
            marked text. The available attributes are: font face, bold,
            italic, font size, color and quote. Calling the function on an
            already marked up word will remove the attribute. If color is
            chosen, a pop up selection window with all the defined groff
            colors is shown.

- <ctrl>-cO will show a one-line menu in the message area whence you may
            change the settings for output device, input encoding, paper
            format and toggle between portrait and landscape paper
            orientation.

- <ctrl>-cC will show the full groff command line, the mode has detected as
            needed to convert the current buffer, in the message area. This
            is similar to what the grog(1) program does.

- <ctrl>-ce will give you a input line in the mini buffer where you may enter
            or edit the groff command to convert the document. This sets the
            value of the variable, "Groff_Cmd", which will override the built-in
            detection mechanism. If you want to revert to auto detection, then
            just clear the line.

- <ctrl>-cp will display a one-line menu in the message area with items for
            drawing various figures with pic(1).

- <ctrl>-cd will display a one-line menu in the message area with items for
            drawing various figures with troff requests.

- <ctrl>-cG will provide a search prompt in the minibuffer where you may
            type in an expression to match a glyph to be searched for in the
            installed font files. A buffer with the results (if any) will
            pop up and you may type in a number corresponding to the glyph
            you want.


Finally, the keys for the functions, forward_paragraph() and
backward_paragraph() will jump forward or backward to regular text portions
of the document, skipping over macros, comments, etc.


                         SEARCHING IN MANUAL PAGES:
                         

If standing on a line with a macro or request, typing <F1> will pop up the
manual page for the active macro package and show the first match of the
macro/request. If standing on a line without a macro or request, a search
prompt will appear where any search expression may be entered in a manual
page of choice. If text is marked beforehand, this text will become the
search expression. The key <F2> is also bound to this latter type of search.


                             USING A MODE HOOK:


When the mode is loaded, a mode hook is run. You may exploit that by
e.g. inserting the following into your ~/.jedrc:

  variable Groff_Pdf_Viewer;
  variable Groff_Show_Warnings;

  define groff_mode_hook ()
  {
    % insert a document template upon loading an empty file
    if (eobp() && bobp()
      insert("document_template.ms")
      
    Groff_Pdf_Viewer = "evince";
    Groff_Show_Warnings = 1;
  }

Send comments, suggestions or bug reports to me:

  Morten Bo Johansen
  mbj at hotmail dot com