path: root/org/manpage.org

-*- mode: org -*-
#+TITLE:       sisu manpage
#+DESCRIPTION: documents - structuring, various output representations & search
#+FILETAGS:    :sisu:manpage:
#+AUTHOR:      Ralph Amissah
#+EMAIL:       [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]]
#+COPYRIGHT:   Copyright (C) 2015 - 2021 Ralph Amissah
#+LANGUAGE:    en
#+STARTUP:     content hideblocks hidestars noindent entitiespretty
#+OPTIONS:     H:3 num:nil toc:t \n:nil @:t ::t |:t ^:nil _:nil -:t f:t *:t <:t
#+PROPERTY:    header-args  :exports code
#+PROPERTY:    header-args+ :noweb yes
#+PROPERTY:    header-args+ :eval no
#+PROPERTY:    header-args+ :results no
#+PROPERTY:    header-args+ :cache no
#+PROPERTY:    header-args+ :padline no
#+PROPERTY:    header-args+ :mkdirp yes

* manpage.rb

#+BEGIN_SRC ruby  :tangle "../lib/sisu/manpage.rb"
# <<sisu_document_header>>
module SiSU_Manpage
  require_relative 'ao'                                 # ao.rb
  require_relative 'se'                                 # se.rb
    include SiSU_Env
  include SiSU_Param
  require_relative 'manpage_format'                     # manpage_format.rb
    include SiSU_ManpageFormat
  require_relative 'shared_metadata'                    # shared_metadata.rb
  require_relative 'generic_parts'                      # generic_parts.rb
  require_relative 'txt_read'                           # txt_read.rb
  require_relative 'txt_output'                         # txt_output.rb
  require_relative 'txt_shared'                         # txt_shared.rb
  @@alt_id_count,@@alt_id_count=0,0
  @@tablefoot=''
  class Source
    include SiSU_Txt_Read
    def initialize(opt)
      @opt=opt
      if @opt.fns =~/(.+?)\.(?:-|ssm\.)?sst$/
        @@notes=:end
      else
        puts "#{sf} not a processed file type"
      end
    end
    def read
      begin
        md=SiSU_Param::Parameters.new(@opt).get
        specific={
          description:     'Manpage',
          output_path:     md.file.output_path.manpage.dir,
          output_file:     md.file.base_filename.manpage,
        }
        read_generic(@opt,specific)
        SiSU_Manpage::Source::Scroll.new(md,@ao_array,@wrap_width).songsheet
      rescue
        SiSU_Errors::Rescued.new($!,$@,@opt.selections.str,@opt.fns).location do
          __LINE__.to_s + ':' + __FILE__
        end
      ensure
        Dir.chdir(@opt.f_pth[:pth])
      end
    end
    private
    class Scroll <Source
      include SiSU_Parts_Generic
      include SiSU_TextUtils
      @@endnotes={ para: [], end: [] }
      def initialize(md,data,wrap_width)
        @md,@data,@wrap_width=md,data,wrap_width
        @tab="\t"
        @@notes=:end
        @manpage={ body: [], open: [], close: [], head: [], metadata: [], tail: [], endnotes: [] }
      end
      def songsheet
        manpage=markup(@data)
        publish(manpage)
      end
      def break_line
        "\n"
      end
      # Used for extraction of endnotes from paragraphs
      def extract_endnotes(dob='')
        para=dob.obj.gsub(/#{Mx[:br_line]}/,"\n")
        notes=para.scan(/(?:#{Mx[:en_a_o]}|#{Mx[:en_b_o]})([\d*+]+(?:\s|\n)+.+?)(?:#{Mx[:en_a_c]}|#{Mx[:en_b_c]})/m)
        @n=[]
        notes.flatten.each do |n| #high cost to deal with <br> appropriately within manpage, consider
          n=n.dup.to_s
          if n =~/#{Mx[:br_line]}|#{Mx[:br_nl]}/
            fix = n.split(/#{Mx[:br_line]}|#{Mx[:br_nl]}/) #watch #added
            fix.each do |x|
              unless x.empty?; @n << x
              end
            end
          else                 @n << n
          end
        end
        notes=@n.flatten
        notes.each do |e|
          util=(e.to_s =~/^\[[\d*+]+\]:/) \
          ? (SiSU_TextUtils::Wrap.new(e.to_s,@wrap_width,4,1))
          : (SiSU_TextUtils::Wrap.new(e.to_s,@wrap_width,0,1))
          wrap=util.line_wrap
          wrap=if wrap =~ /^\s*[\d*+]+\s+.+?\s*\Z/m
            wrap.gsub(/(^|&nbsp;|#{Mx[:nbsp]}|\s|\*)\\\*/,'\1\\\\\*'). #man page requires
              gsub(/\s(.[BI])\s/,' ').
              gsub(/\s\.(\S+)/,' \\.\1').
              gsub(/^\s*([\d*+]+)\s+(.+?)\s*\Z/m, <<GSUB
.TP
.BI \\1.
\\2
GSUB
                      )
          else
            wrap.gsub(/^\s*(.+)\Z/m, <<GSUB
\\1
GSUB
                      )
          end
          @@endnotes[:para] << wrap
          @@endnotes[:end] << wrap << "\n.BR"
          @@endnotes
        end
      end
      def manpage_metadata
        @manpage[:metadata]=SiSU_Metadata::Summary.new(@md).manpage.metadata
      end
      def manpage_tail
        @manpage[:tail] <<<<WOK
#{break_line}
.TP
.SH SEE ALSO
       sisu(1),
       sisu-epub(1),
       sisu-harvest(1),
       sisu-html(1),
       sisu-odf(1),
       sisu-pdf(1),
       sisu-pg(1),
       sisu-sqlite(1),
       sisu-txt(1).
       sisu_vim(7)
.TP
.SH HOMEPAGE
       More information about SiSU can be found at <http://www.sisudoc.org/> or <http://www.jus.uio.no/sisu/>
.TP
.SH SOURCE
       <http://git.sisudoc.org/>
.TP
.SH AUTHOR
       SiSU is written by Ralph Amissah [ralph@amissah.com]
WOK
      end
      def manpage_structure(dob='',hname='') #% Used to extract the structure of a document
        if dob.is==:heading
          lv=dob.ln
          dob.ln + 2
        else lv=nil
        end
        wrapped=if dob.is==:para \
        || dob.is==:heading
          paragraph=dob.obj
          if dob.is==:para
            if dob.indent =~/[1-9]/ \
            and dob.indent == dob.hang
              util=if dob.bullet_
                SiSU_TextUtils::Wrap.new("* #{paragraph}",@wrap_width,dob.indent.to_i*2)
              else SiSU_TextUtils::Wrap.new(paragraph,@wrap_width,dob.indent.to_i*2)
              end
            elsif dob.hang =~/[0-9]/ \
            and dob.indent != dob.hang                     # NOT yet implemented
              util=SiSU_TextUtils::Wrap.new(paragraph,@wrap_width,dob.indent.to_i*2)
            else
              util=if dob.bullet_
                SiSU_TextUtils::Wrap.new("* #{paragraph}",@wrap_width,0)
              else SiSU_TextUtils::Wrap.new(paragraph,@wrap_width,0)
              end
            end
          else util=SiSU_TextUtils::Wrap.new(paragraph,@wrap_width,0)
          end
          w=util.line_wrap
          w=w.gsub(/^(\\\.)/,' \1')
          w
        end
        if lv
          times=wrapped.length
          times=@wrap_width if times > @wrap_width
          @manpage[:body] << case lv
          when 0    then '.SH ' << wrapped.upcase << break_line << break_line
          when 1..3 then '.SH ' << wrapped.upcase << break_line << break_line
          when 4    then '.SH ' << wrapped.upcase << break_line << break_line
          when 5..6 then '.SH ' << wrapped.upcase << break_line << break_line
          end
        else
          @manpage[:body] << if  wrapped =~/^\.BI\s/ # main text, contents, body KEEP
            '.TP' << break_line << wrapped.gsub(/(^\.B)I\s/,'\1 ') # sleight ... simpler output (check gsub!)
          else
            break_line + '.BR' + break_line << wrapped
          end
        end
        if @@endnotes[:para] \
        and @@notes==:foot #edit out to switch off endnotes following paragraph to which they belong
          @@endnotes[:para].each { |e| @manpage[:body] << e << break_line }
        elsif @@endnotes[:para] \
        and @@notes==:end
        end
        @@endnotes[:para]=[]
      end
      def markup(data)                                                       # Used for major markup instructions
        SiSU_Env::InfoEnv.new(@md.fns)
        @data_mod,@endnotes,@level,@cont,@copen,@manpage_contents_close=Array.new(6){[]}
        (0..6).each { |x| @cont[x]=@level[x]=false }
        (4..6).each { |x| @manpage_contents_close[x]='' }
        #manpage_tail # stop call
        table_message='[table omitted, see other document formats]'
        #manpage_metadata
        data.each do |dob|
          if dob.is==:comment \
          || dob.is==:heading_insert
            dob.obj=''
          end
          dob.obj=dob.obj.gsub(/.+?<-#>/,'').                                           # remove dummy headings (used by html) #check
            gsub(/#{Mx[:fa_superscript_o]}(.+?)#{Mx[:fa_superscript_c]}/,'^\1^').
            gsub(/#{Mx[:fa_subscript_o]}(.+?)#{Mx[:fa_subscript_c]}/,'[\1]').
            gsub(/#{Mx[:fa_insert_o]}(.+?)#{Mx[:fa_insert_c]}/,'++\1++').
            gsub(/#{Mx[:fa_strike_o]}(.+?)#{Mx[:fa_strike_c]}/,'--\1--').
            gsub(/#{Mx[:fa_cite_o]}(.+?)#{Mx[:fa_cite_c]}/,'"\1"').
            gsub(/#{Mx[:fa_monospace_o]}(.+?)#{Mx[:fa_monospace_c]}/,'\1').
            gsub(/\A\s*#{Mx[:fa_italics_o]}(.+?)#{Mx[:fa_italics_c]}#{Mx[:br_line]}([,.:!?](?: |$))?/m,
              "#{Mx[:br_line]}.I \\1\\2#{Mx[:br_line]}").
            gsub(/\s*#{Mx[:fa_italics_o]}(.+?)#{Mx[:fa_italics_c]}([,.:!?](?: |$))?/m,
              "#{Mx[:br_line]}.I \\1\\2#{Mx[:br_line]}").
            gsub(/\A\s*#{Mx[:fa_bold_o]}(.+?)#{Mx[:fa_bold_c]}([,.:!?](?: |$))?#{Mx[:br_line]}/m,
              "\n.BI \\1\\2#{Mx[:br_line]}").
            gsub(/\s*#{Mx[:fa_bold_o]}(.+?)#{Mx[:fa_bold_c]}([,.:!?](?: |$))?/m,
              "#{Mx[:br_line]}.B \\1\\2#{Mx[:br_line]}").
            gsub(/\s*#{Mx[:fa_underscore_o]}(.+?)#{Mx[:fa_underscore_c]}([,.:!?](?: |$))?/,
              "\n.I \\1\\2#{Mx[:br_line]}")
          unless dob.is==:code
            dob.obj=dob.obj.gsub(/(?:^|\s)#{Mx[:lnk_o]}(.+?)#{Mx[:lnk_c]}#{Mx[:url_o]}(\S+?)#{Mx[:url_c]}([,.:!?](?: |$))?/,
                "\\1 #{the_text.url_open}\\2#{the_text.url_close}\\3").
              gsub(/(^|#{Mx[:gl_c]}|\s)#{Mx[:url_o]}(\S+?)#{Mx[:url_c]}([,.:!?](?: |$))?/,
                "\\1#{the_text.url_open}\\2#{the_text.url_close}\\3")
            @manpage[:endnotes]=extract_endnotes(dob)
            dob.obj=dob.obj.gsub(/#{Mx[:en_a_o]}([\d*+]+)\s*(?:.+?)#{Mx[:en_a_c]}/m,'[^\1]'). # endnote marker marked up
              gsub(/#{Mx[:en_b_o]}([\d*+]+)\s*(?:.+?)#{Mx[:en_b_c]}/m,'[^\1]'). # endnote marker marked up
              gsub(/#{Mx[:gl_o]}#amp#{Mx[:gl_c]}/,'&'). ##{Mx[:gl_o]}#095#{Mx[:gl_c]}
              gsub(/#{Mx[:gl_o]}#033#{Mx[:gl_c]}/,'!').
              gsub(/#{Mx[:gl_o]}#035#{Mx[:gl_c]}/,'#').
              gsub(/#{Mx[:gl_o]}#042#{Mx[:gl_c]}/,'*').
              gsub(/#{Mx[:gl_o]}#045#{Mx[:gl_c]}/,'-').
              gsub(/#{Mx[:gl_o]}#092#{Mx[:gl_c]}/,'\e').
              gsub(/#{Mx[:gl_o]}#047#{Mx[:gl_c]}/,'/').
              gsub(/#{Mx[:gl_o]}#095#{Mx[:gl_c]}/,'_').
              gsub(/#{Mx[:gl_o]}#123#{Mx[:gl_c]}/,'{').
              gsub(/#{Mx[:gl_o]}#125#{Mx[:gl_c]}/,'}').
              gsub(/#{Mx[:gl_o]}#126#{Mx[:gl_c]}/,'~').
              gsub(/#{Mx[:gl_o]}#169#{Mx[:gl_c]}/,'©')
          else
            dob.obj=dob.obj.gsub(/\\/,'\e').
              gsub(/(?:#{Mx[:br_line]}|#{Mx[:br_nl]})\s*/,"\n")                          # watch
          end
          dob.obj=dob.obj.gsub(/(^|&nbsp;|#{Mx[:nbsp]}|\s|\*)\\\*/,'\1\\\\\*').          #man page requires
            gsub(/┆/,'|').
            gsub(/^(\.\S{3,})/m,' \1')                                                   # ^\. used by interpreter, disable when use not intended
          dob.obj=dob.obj.gsub(/&#126;/,'~') if dob.obj #manpages use this
          if dob.is ==:code
            dob.obj=dob.obj.gsub(/(^|[^}])_([<>])/m,'\1\2'). # _> _<
              gsub(/(^|[^}])_([<>])/m,'\1\2'). # _<_<
              gsub(/(?:#{Mx[:br_line]}|#{Mx[:br_nl]})+(\s*)/m,"\n\\1").                  # watch
              gsub(/\A(.+?)\s*\Z/m,".nf\n\\1\n.fi")
          end
          dob.obj=dob.obj.gsub(/(?:#{Mx[:br_line]}|#{Mx[:br_nl]})+\s*/m,"\n\n")          # watch
          dob.obj=dob.obj.gsub(/#{Mx[:gl_o]}:name#\S+?#{Mx[:gl_c]}/mi,'').               #added
            gsub(/#{Mx[:br_page]}\s*|#{Mx[:br_page_new]}|#{Mx[:br_page_line]}/,'').      # remove page breaks, you may wish to have a line across the page break instead
            gsub(/(^|#{Mx[:gl_c]}|\s)#{Mx[:url_o]}_(\S+?)#{Mx[:url_c]}/,'\1\2').
            gsub(/<a href=".+?">(.+?)<\/a>/m,'\1').
            gsub(/#{Mx[:mk_o]}name#\S+?#{Mx[:mk_c]}/,'').                                # remove name links
            gsub(/&nbsp;|#{Mx[:nbsp]}/,' ').                                             # decide on
            gsub(/(?:^|[^_\\])#{Mx[:lnk_o]}\s*(\S+?\.(?:png|jpg|gif)) .+?#{Mx[:lnk_c]}#{Mx[:url_o]}\S+?#{Mx[:url_c]}/,'    [ \1 ]'). #"[ #{dir.url.images_local}\/\\1 ]")
            gsub(/(?:^|[^_\\])#{Mx[:lnk_o]}\s*(\S+?\.(?:png|jpg|gif)) .+?#{Mx[:lnk_c]}image/,'    [ \1 ]'). #"[ #{dir.url.images_local}\/\\1 ]")
            gsub(/^(?:^|[^_\\])#{Mx[:lnk_o]}\s*\S+?\.(?:png|jpg|gif)\s+.+?"(.*?)"\s*#{Mx[:lnk_c]}\S+/,'[image: "\1"]')
          if dob.obj !~/(^#{Rx[:meta]}|#{Mx[:br_eof]}|#{Mx[:br_endnotes]})/
            if dob.obj =~@regx #/.+?<~\d+;\w\d+;\w\d+>.*/ #watch change
              paranum=dob.obj[@regx,3]
              @p_num=SiSU_ManpageFormat::ParagraphNumber.new(paranum)
            end
            SiSU_ManpageFormat::FormatTextObject.new(@md,dob) #check
            if dob.is==:heading
              manpage_structure(dob)
            elsif dob.is==:para
              manpage_structure(dob)
            else
              if dob.obj =~/#{table_message}/
                @manpage[:body] << dob.obj << break_line
              end
            end
            if (dob.obj =~/<a name="n\d+">/ \
            and dob.obj =~/^(-\{{2}~\d+|<!e[:_]\d+!>)/) # -endnote
              dob.obj=''
            end
            if dob.obj
              dob.obj=dob.obj.gsub(/(?:#{Mx[:br_line]}|#{Mx[:br_nl]})\s*/,"\n\n").                                   # watch
                gsub(/#{Mx[:gl_o]}#126#{Mx[:gl_c]}/,'~').
                gsub(/#{Mx[:gl_o]}#123#{Mx[:gl_c]}/,'{').
                gsub(/#{Mx[:pa_o]}\S+#{Mx[:pa_c]}/,' ')
              unless dob.is ==:code
                dob.obj=dob.obj.gsub(/<!.+!>/,' ').
                  gsub(/<:\S+>/,' ')
              end
            end
            dob
          end
        end
        @manpage
      end
      def publish(manpage)
        content=[]
        date=if defined? @md.date.modified \
        and @md.date.modified
          @md.date.modified
        elsif defined? @md.date.published \
        and @md.date.published
          @md.date.published
        else SiSU_Env::InfoDate.new.year #date missing decide on action
        end
        proj=SiSU_Env::InfoVersion.instance.get_version
        manpage[:open] = %{.TH "#{@md.fnb}" "#{@md.make.manpage['section']}" "#{date}" "#{proj.version}" "#{@md.title.main}"#{@md.make.manpage['name']}#{@md.make.manpage['synopsis']}}
        content << manpage[:open]
        content << manpage[:head]
        content << manpage[:body]
        content << @@endnotes[:end] if @@notes==:end
        content << manpage[:metadata]
        content << manpage[:tail]
        outputfile=SiSU_Env::FileOp.new(@md).write_file.manpage
        Txt_Output::Output.new.document(content,outputfile)
        @@endnotes={ para: [], end: [] }
      end
    end
  end
end
__END__
#+END_SRC

* manpage_format.rb

#+BEGIN_SRC ruby  :tangle "../lib/sisu/manpage_format.rb"
# <<sisu_document_header>>
module SiSU_ManpageFormat
  require_relative 'dp'                                 # dp.rb
    include SiSU_Param
  class ParagraphNumber
    def initialize(paranum)
      @paranum=/(\d+)/m.match(paranum)[1]
    end
    def display
      @paranum.gsub(/(\d+)/,'<font size="1" color="#777777">&nbsp;&nbsp;\1</font>')
    end
    def name
      @paranum.gsub(/(\d+)/,'<a name="\1"></a>')
    end
    def goto
      @paranum.gsub(/(\d+)/,'<a href="#\1">')
    end
  end
  class FormatTextObject
    def initialize(md,dob)
      @md,@dob=md,dob
      rgx=/#{Mx[:en_a_o]}[\d*+]+\s+(.+?)#{Mx[:en_a_c]}/
      @dob.obj.gsub!(rgx,'\1') if @dob.obj =~rgx
    end
    def scr_endnote_body
      "<endnote>#{@dob.obj}</endnote> "
    end
  end
end
__END__
#+END_SRC

* document header

#+NAME: sisu_document_header
#+BEGIN_SRC text
encoding: utf-8
- Name: SiSU

  - Description: documents, structuring, processing, publishing, search
    manpage

  - Author: Ralph Amissah
    <ralph.amissah@gmail.com>

  - Copyright: (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
    2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2019,
    2020, 2021, Ralph Amissah,
    All Rights Reserved.

  - License: GPL 3 or later:

    SiSU, a framework for document structuring, publishing and search

    Copyright (C) Ralph Amissah

    This program is free software: you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the Free
    Software Foundation, either version 3 of the License, or (at your option)
    any later version.

    This program is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
    FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
    more details.

    You should have received a copy of the GNU General Public License along with
    this program. If not, see <http://www.gnu.org/licenses/>.

    If you have Internet connection, the latest version of the GPL should be
    available at these locations:
    <http://www.fsf.org/licensing/licenses/gpl.html>
    <http://www.gnu.org/licenses/gpl.html>

    <http://www.sisudoc.org/sisu/en/manifest/gpl.fsf.html>

  - SiSU uses:
    - Standard SiSU markup syntax,
    - Standard SiSU meta-markup syntax, and the
    - Standard SiSU object citation numbering and system

  - Homepages:
    <http://www.sisudoc.org>

  - Git
    <https://git.sisudoc.org/projects/>
    <https://git.sisudoc.org/projects/?p=software/sisu.git;a=summary>
    <https://git.sisudoc.org/projects/?p=markup/sisu-markup-samples.git;a=summary>
#+END_SRC