dm_roff Module

Module for creating formatted output in GNU roff (with ms macro package by default).

In order to create PostScript and PDF files, groff(1) must be installed. On Linux, run:

$ sudo apt-get install ghostscript groff

Create a PDF report from ms markup:

character(:), allocatable :: roff
integer                   :: rc

! Generate markup with macro package -ms.
roff = dm_roff_ms_header(title='Test Report', author='Sensor Node 1', &
                         institution='University of Elbonia', &
                         font_family=ROFF_FONT_HELVETICA, &
                         left_footer=dm_time_date(), &
                         right_footer='DMPACK ' // DM_VERSION_STRING)
roff = roff // dm_roff_ms_sh(2, 'Results')
roff = roff // dm_roff_ms_lp('First paragraph.')

! Create PDF from markup.
rc = dm_roff_to_pdf(roff, '/tmp/report.pdf', macro=ROFF_MACRO_MS)

Uses

  • module~~dm_roff~~UsesGraph module~dm_roff dm_roff module~dm_ascii dm_ascii module~dm_roff->module~dm_ascii module~dm_error dm_error module~dm_roff->module~dm_error module~dm_kind dm_kind module~dm_roff->module~dm_kind module~dm_util dm_util module~dm_roff->module~dm_util module~dm_error->module~dm_ascii module~dm_error->module~dm_kind iso_fortran_env iso_fortran_env module~dm_kind->iso_fortran_env module~dm_util->module~dm_error module~dm_util->module~dm_kind

Used by

  • module~~dm_roff~~UsedByGraph module~dm_roff dm_roff module~dmpack dmpack module~dmpack->module~dm_roff

Variables

Type Visibility Attributes Name Initial
integer, public, parameter :: ROFF_DEVICE_NONE = 0

Invalid device.
integer, public, parameter :: ROFF_DEVICE_UTF8 = 1

Plain text (UTF-8).
integer, public, parameter :: ROFF_DEVICE_PS = 2

PostScript.
integer, public, parameter :: ROFF_DEVICE_PDF = 3

PDF.
integer, public, parameter :: ROFF_DEVICE_HTML = 4

HTML 4.01.
integer, public, parameter :: ROFF_DEVICE_LAST = 4

Never use this.
integer, public, parameter :: ROFF_DEVICE_NAME_LEN = 4

Max. device name length.
character(len=*), public, parameter :: ROFF_DEVICE_NAMES(ROFF_DEVICE_NONE:ROFF_DEVICE_LAST) = [character(ROFF_DEVICE_NAME_LEN)::'none', 'utf8', 'ps', 'pdf', 'html']

Device names.
integer, public, parameter :: ROFF_MACRO_NONE = 0

No macro package.
integer, public, parameter :: ROFF_MACRO_MS = 1

Macro package -ms.
integer, public, parameter :: ROFF_MACRO_LAST = 1

Never use this.
integer, public, parameter :: ROFF_FONT_NONE = 0

Default font (Times Roman).
integer, public, parameter :: ROFF_FONT_AVANT_GARDE = 1

Avant Garde.
integer, public, parameter :: ROFF_FONT_BOOKMAN = 2

Bookman.
integer, public, parameter :: ROFF_FONT_HELVETICA = 3

Helvetica.
integer, public, parameter :: ROFF_FONT_HELVETICA_NARROW = 4

Helvetica Narrow.
integer, public, parameter :: ROFF_FONT_NEW_CENTURY_SCHOOLBOOK = 5

New Century Schoolbook.
integer, public, parameter :: ROFF_FONT_PALATINO = 6

Palatino.
integer, public, parameter :: ROFF_FONT_TIMES_ROMAN = 7

Times Roman.
integer, public, parameter :: ROFF_FONT_ZAPF_CHANCERY = 8

Zapf Chancery (italic only).
integer, public, parameter :: ROFF_FONT_LAST = 8

Never use this.
integer, public, parameter :: ROFF_FONT_NAME_LEN = 3

Max. font name length.
character(len=*), public, parameter :: ROFF_FONT_NAMES(ROFF_FONT_NONE:ROFF_FONT_LAST) = [character(ROFF_FONT_NAME_LEN)::'T', 'A', 'BM', 'H', 'HN', 'N', 'P', 'T', 'ZCM']

Font family names.
character(len=*), public, parameter :: ROFF_REQUEST_BP = '.bp'//NL

Page break.
character(len=*), public, parameter :: ROFF_REQUEST_BR = '.br'//NL

Line break.
character(len=*), public, parameter :: ROFF_REQUEST_MS_P1 = '.P1'//NL

Typeset header on page 1 (ms).
character(len=*), public, parameter :: ROFF_ESC_DUMMY = '\&'

Interpolate a dummy character.
character(len=*), public, parameter :: ROFF_ESC_EMDASH = '\[em]'

em dash.
character(len=*), public, parameter :: ROFF_ESC_ENDASH = '\[en]'

en dash.
character(len=*), public, parameter :: ROFF_ESC_HR = "\l'\n(.lu'"

Horizontal rule.
character(len=*), public, parameter :: ROFF_ESC_HYPHEN = '\[hy]'

Hyphen.
character(len=*), public, parameter :: ROFF_ESC_MVUP = '\u'

Move ½ em up.
character(len=*), public, parameter :: ROFF_ESC_NBSP = '\~'

None-breaking space.
character(len=*), public, parameter :: ROFF_ENCODING_UTF8 = '.\" -*- mode: troff; coding: utf-8 -*-'//NL

UTF-8 encoding for preconv.

Interfaces

public interface dm_roff_ms_nr

Generic macro function to set register value.

  • private pure function roff_ms_nr_int32(register, value, unit) result(roff)

    Returns macro to set register value (4-byte integer).

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: register

    Register name.
    integer(kind=i4), intent(in) :: value

    Register value.
    character(len=*), intent(in), optional :: unit

    Optional unit.

    Return Value character(len=:), allocatable

    Output string.

  • private pure function roff_ms_nr_real32(register, value, unit) result(roff)

    Returns macro to set register value (4-byte real).

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: register

    Register name.
    real(kind=r4), intent(in) :: value

    Register value.
    character(len=*), intent(in), optional :: unit

    Optional unit.

    Return Value character(len=:), allocatable

    Output string.


Functions

public pure elemental function dm_roff_device_is_valid(device) result(is)

Returns .true. if argument device is a valid device enumerator.

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: device

Device type (ROFF_MACRO_*).

Return Value logical

public pure elemental function dm_roff_macro_is_valid(macro) result(is)

Returns .true. if argument macro is a valid macro enumerator.

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: macro

Macro type (ROFF_MACRO_*).

Return Value logical

public function dm_roff_ps_to_pdf(input, output) result(rc)

Converts PostScript file input to PDF file output by executing ps2pdf(1). On error, an empty PDF file may be created. This function requires Ghostscript to be installed locally.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: input

Path of PostScript file.
character(len=*), intent(in) :: output

Path of PDF file.

Return Value integer

public function dm_roff_to_pdf(roff, path, macro, pic, preconv, tbl) result(rc)

Passes the markup string roff to groff(1) to create a PDF file that is written to path. An existing file will not be replaced. On error, an empty file may still be created. By default, this function uses macro package ms, unless argument macro is passed.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(inout) :: roff

Markup string.
character(len=*), intent(in) :: path

Path of output file.
integer, intent(in), optional :: macro

Macro package to use (ROFF_MACRO_*).
logical, intent(in), optional :: pic

Run pic preprocessor.
logical, intent(in), optional :: preconv

Run preconv preprocessor.
logical, intent(in), optional :: tbl

Run tbl preprocessor.

Return Value integer

public function dm_roff_to_ps(roff, path, macro, pic, preconv, tbl) result(rc)

Passes the markup string roff to groff(1) to create a PostScript file that is written to path. An existing file will not be replaced. On error, an empty file may still be created. By default, this function uses macro package ms, unless argument macro is passed.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(inout) :: roff

Markup string.
character(len=*), intent(in) :: path

Path of output file.
integer, intent(in), optional :: macro

Macro package to use (ROFF_MACRO_*).
logical, intent(in), optional :: pic

Run pic preprocessor.
logical, intent(in), optional :: preconv

Run preconv preprocessor.
logical, intent(in), optional :: tbl

Run tbl preprocessor.

Return Value integer

public function dm_roff_version(name, found) result(version)

Returns GNU roff version as allocatable string.

Arguments

Type IntentOptional Attributes Name
logical, intent(in), optional :: name

Add prefix groff/.
logical, intent(out), optional :: found

Returns .true. if groff has been found.

Return Value character(len=:), allocatable

Version string.

public pure function dm_roff_ms_header(title, author, institution, font_family, font_size, left_header, center_header, right_header, left_footer, center_footer, right_footer, page_one) result(roff)

Creates a new GNU roff document with macro package ms. The result has to be piped to groff(1).

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in), optional :: title

Document title.
character(len=*), intent(in), optional :: author

Author name.
character(len=*), intent(in), optional :: institution

Institution name.
integer, intent(in), optional :: font_family

Font family enumerator (ROFF_FONT_*).
integer, intent(in), optional :: font_size

Font size in pt.
character(len=*), intent(in), optional :: left_header

Left header content.
character(len=*), intent(in), optional :: center_header

Center header content.
character(len=*), intent(in), optional :: right_header

Right header content.
character(len=*), intent(in), optional :: left_footer

Left footer content.
character(len=*), intent(in), optional :: center_footer

Center footer content.
character(len=*), intent(in), optional :: right_footer

Right footer content.
logical, intent(in), optional :: page_one

Enable header on page 1.

Return Value character(len=:), allocatable

Output string.

public function dm_roff_tbl(format, data, all_box, box, double_box, center, expand, no_spaces) result(roff)

Returns table markup for tbl(1).

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(inout) :: format(:,:)

Table format.
character(len=*), intent(inout) :: data(:,:)

Table data.
logical, intent(in), optional :: all_box

Encloses each item of the table in a box.
logical, intent(in), optional :: box

Encloses the table in a box.
logical, intent(in), optional :: double_box

Encloses the table in a double box.
logical, intent(in), optional :: center

Centers the table (default is left-justified).
logical, intent(in), optional :: expand

Makes the table as wide as the current line length.
logical, intent(in), optional :: no_spaces

Ignore leading and trailing spaces in data items.

Return Value character(len=:), allocatable

Output string.

public pure function dm_roff_defcolor(ident, r, g, b) result(roff)

Returns request to define a named stroke colour.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: ident

Colour identifier.
integer, intent(in) :: r

Red channel.
integer, intent(in) :: g

Green channel.
integer, intent(in) :: b

Blue channel.

Return Value character(len=:), allocatable

Output string.

public pure function dm_roff_m(ident, text) result(roff)

Returns escape sequence to change stroke colour of text to identifier ident. The identifier has to be defined with dm_roff_defcolor() beforehand. The result is not new-line terminated!

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: ident

Colour identifier.
character(len=*), intent(in) :: text

Text.

Return Value character(len=:), allocatable

Output string.

public pure function dm_roff_pspic(path, align, width, height) result(roff)

Returns .PSPIC macro to add image in Encapsulated PostScript (EPS) format. Argument align must be either L (left), R (right), or C (center). If not passed, the image will be centered.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: path

Path to EPS file.
character(len=1), intent(in), optional :: align

Image alignment (L, R, C).
real, intent(in), optional :: width

Image width [cm].
real, intent(in), optional :: height

Image height [cm].

Return Value character(len=:), allocatable

Output string.

public pure function dm_roff_s(n, text, rel) result(roff)

Returns escape sequence to change type size. Argument n must be single digit. The result is not new-line terminated!

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: n

Absolute or relative size [pt].
character(len=*), intent(in) :: text

Text.
character(len=1), intent(in), optional :: rel

+ or -.

Return Value character(len=:), allocatable

Output string.

public pure function dm_roff_sp(distance, unit) result(roff)

Returns request to add vertical spacing.

Arguments

Type IntentOptional Attributes Name
integer, intent(in), optional :: distance

Vertical space.
character(len=1), intent(in), optional :: unit

Distance unit. Uses [vee] is not passed.

Return Value character(len=:), allocatable

Output string.

public pure function dm_roff_tbl_block(text) result(roff)

Returns argument text between T{ and T} to create a text block.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: text

Text.

Return Value character(len=:), allocatable

Output string.

public pure function dm_roff_ms_ai(institution) result(roff)

Returns macro to add institution of author(s). Multiple institutions have to be separated by new line.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: institution

Institution name.

Return Value character(len=:), allocatable

Output string.

public pure function dm_roff_ms_au(author) result(roff)

Returns macro to add author. Multiple authors have to be separated by new line.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: author

Author name.

Return Value character(len=:), allocatable

public pure function dm_roff_ms_bx(text) result(roff)

Returns macro to draw a box around text. This function does not append a new-line character!

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: text

Text.

Return Value character(len=:), allocatable

public pure function dm_roff_ms_ds(name, string) result(roff)

Returns macro to define a string.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: name

String name.
character(len=*), intent(in), optional :: string

String contents.

Return Value character(len=:), allocatable

Output string.

public pure function dm_roff_ms_lp(text) result(roff)

Returns macro to add paragraph (without indent).

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in), optional :: text

Paragraph text.

Return Value character(len=:), allocatable

Output string.

public pure function dm_roff_ms_nh(level, text) result(roff)

Returns macro to set section heading macro (without number).

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: level

Heading level (depth).
character(len=*), intent(in) :: text

Heading text.

Return Value character(len=:), allocatable

Output string.

public pure function dm_roff_ms_pp(text) result(roff)

Returns macro to add standard paragraph.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in), optional :: text

Paragraph text.

Return Value character(len=:), allocatable

Output string.

public pure function dm_roff_ms_sh(level, text) result(roff)

Returns macro to add section heading (without number).

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: level

Heading level (depth).
character(len=*), intent(in) :: text

Heading text.

Return Value character(len=:), allocatable

Output string.

public pure function dm_roff_ms_tl(title) result(roff)

Returns macro to add title.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: title

Title.

Return Value character(len=:), allocatable

Output string.