A command-line tool to generate Linux manual pages from C source code.

Related tags

CLI mangen
Overview

mangen

A command-line tool to generate Linux manual pages from C source code.

Description

mangen is, as said above, a program to generate Linux manual pages from C source code. At invocation, mangen is given a type of token to generate manual pages for, like a file overview, or for specific functions, and then it is given files to operate on.

Example using looks like so:

mangen token [FILE] ... [OPTIONS]

Tokens

mangen can handle several types of tokens to generate manual pages for. What follows is each token, and a brief explanation of it.

overview - produce an 'overview' of all the files given, using block comments at the top of the file, as well as some other parts of the file to generate the manual page, like for constants.

function - produce unique manual pages for each function in each source code file provided, extracting data from a block comment at the top of each function.

Design

To keep things modular, and possibly extendable, mangen generators are segmented into their own files, and are invoked through mangen's entry point. When the correct token is determined, the arguments are passed to the chosen generator, where argument parsing continues. This allows for individual generators to have their own configuration.

When mangen is invoked, mangen will create a new mangen-docs folder, where the chosen generator will dump its manuals into. However, the generator will make its own unique folder inside of mangen-docs. For example, mangen overview will create a folder named overview inside mangen-docs. This is to keep things organized.

Syntax

mangen's syntax is composed of 'tags' which act as directives to the generator of choice. All tags are grouped inside of a 'start' and 'end' tag. For example, an overview of a main file might be:

/*
* @mg_start
* Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer sagittis
* turpis et nulla vulputate tristique. Maecenas euismod urna ut nulla eleifend
* vulputate. Nullam non augue vel dolor cursus volutpat nec vel diam. Vivamus
* nec arcu lacus. Praesent a eros a nunc gravida egestas tincidunt nec dui.
* Donec ut laoreet magna.
* @mg_end
*/

Where tags can be parsed, they must be grouped inside of an mg_start and mg_end tag. Inside of these groups, there are 'blocks' and 'attributes.' Blocks are used to group text into sections, like a description, or synopsis. An attribute is a one-line tag that is used to attach metadata to the manual page, like version number, standards conforming, etc. For example:

/*
 * @mg_start
 * @description_start
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer sagittis
 * turpis et nulla vulputate tristique. Maecenas euismod urna ut nulla eleifend
 * vulputate. Nullam non augue vel dolor cursus volutpat nec vel diam. Vivamus
 * nec arcu lacus. Praesent a eros a nunc gravida egestas tincidunt nec dui.
 * Donec ut laoreet magna.
 * @description_end
 *
 * @conforming This program conforms to C89.
 * @see_also lorem(3), ipsum(3), dolor(3)
 *
 * @mg_end
*/

An important tag that must be included in every block is the 'type' tag. This describes what kind of group it is describing, like a function, macro, or overview. Building upon our previous example:

/*
 * @mg_start
 * @type function
 *
 * @description_start
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer sagittis
 * turpis et nulla vulputate tristique. Maecenas euismod urna ut nulla eleifend
 * vulputate. Nullam non augue vel dolor cursus volutpat nec vel diam. Vivamus
 * nec arcu lacus. Praesent a eros a nunc gravida egestas tincidunt nec dui.
 * Donec ut laoreet magna.
 * @description_end
 *
 * @conforming This program conforms to C89.
 * @see_also lorem(3), ipsum(3), dolor(3)
 *
 * @mg_end
*/

The 'type' tag must always be the first tag after mg_start.

Rationale

To put it simply, I feel like manual pages (and offline documentation in general) is quite an underrated resource. I find that roff, while not terrible, often times involves writing what is essentially boilerplate in textual form. It is also irritating to search through existing manual pages to update things when I could simply have a tool automatically regenerate it, while also taking advantage of something such as Make for generating documentation.

Owner
there's no problem that can't be solved with enough regular expressions and self loathing
null
nicegraf-shaderc is a command-line tool that transforms HLSL code into shaders for various graphics APIs.

User Manual Table of Contents Introduction Project Status Obtaining the Source Code and Building Running Defining Techniques Generated Header File Pip

nicebyte 88 Jun 20, 2022
Toybox: all-in-one Linux command line.

Toybox: all-in-one Linux command line.

Rob Landley 1.7k Jun 29, 2022
pbr2gltf2 is a command line tool for converting PBR images to a glTF 2.0 material.

pbr2gltf2 is a command line tool for converting PBR images to a glTF 2.0 material. The tool is detecting depending on the filename, which PBR information is stored. It swizzles the images and does reassign the channels to a glTF 2.0 image. The tool stores the images plus a minimal, valid glTF 2.0 file containing the required material, textures and images.

UX3D GmbH 22 Jan 11, 2022
A command-line tool to display colorful distro information.

sjfetch A command-line tool to display colorful distro information.

Fikret Musk 6 Apr 6, 2022
Simple command line tool that processes image files using the FidelityFX Super Resolution (FSR) or Contrast Adaptive Sharpening (CAS) shader systems.

Simple command line tool that processes image files using the FidelityFX Super Resolution (FSR) or Contrast Adaptive Sharpening (CAS) shader systems.

GPUOpen Effects 174 Jun 26, 2022
A command line tool with no external dependencies to print information about an X server instance.

xinfo A command line tool with no external dependencies to print information about an X server instance. Building and running To build the code in thi

Jean-Michel Gorius 6 Jan 13, 2022
A command line tool for numerically computing Out-of-time-ordered correlations for N=4 supersymmetric Yang-Mills theory and Beta deformed N=4 SYM.

A command line tool to compute OTOC for N=4 supersymmetric Yang–Mills theory This is a command line tool to numerically compute Out-of-time-ordered co

Gaoli Chen 1 Oct 16, 2021
A command-line tool to extract dylib files from the dyld shared cache file.

DyldExtractor A command-line tool to extract dylib files from the dyld shared cache file. Starting with macOS 11, standalone binaries of system librar

Cyandev 8 Mar 12, 2022
Microsoft Visual TrueType(VTT) command line compile tool.

Project Microsoft Visual TrueType(VTT) is a professional-level tool for graphically instructing TrueType and OpenType fonts. For details on the tool v

Microsoft 34 May 19, 2022
brn is a command line tool similar to vimv.

brn is a command line tool similar to vimv. It can be used to easily mass-rename files in your preferred text editor (i.e. vim).

Nimai Patel 12 Feb 26, 2022
This command-line tool converts an FM broadcast signal into stereo sound with de-emphasis applied.

stereodemux This command-line tool converts an FM broadcast signal into stereo sound with de-emphasis applied. It expects 16-bit signed-integer MPX (F

Oona Räisänen 9 Jun 11, 2022
A single header C++ library for parsing command line arguments and options with minimal amount of code

Quick Arg Parser Tired of unwieldy tools like getopt or argp? Quick Arg Parser is a single header C++ library for parsing command line arguments

null 44 Feb 21, 2022
null 76 Apr 18, 2022
A simple command line application in order to create new Code workspaces.

mkcws Summary A simple command line application in order to create new Code workspaces. License This project's license is GPL 2. The whole license tex

Kevin Matthes 0 Apr 1, 2022
A simple to use, composable, command line parser for C++ 11 and beyond

Clara v1.1.5 !! This repository is unmaintained. Go here for a fork that is somewhat maintained. !! A simple to use, composable, command line parser f

Catch Org 651 Jun 15, 2022
A library for interactive command line interfaces in modern C++

cli A cross-platform header only C++14 library for interactive command line interfaces (Cisco style) Features Header only Cross-platform (linux and wi

Daniele Pallastrelli 803 Jul 2, 2022
CLI11 is a command line parser for C++11 and beyond that provides a rich feature set with a simple and intuitive interface.

CLI11: Command line parser for C++11 What's new • Documentation • API Reference CLI11 is a command line parser for C++11 and beyond that provides a ri

null 2.1k Jun 24, 2022
Lightweight C++ command line option parser

Release versions Note that master is generally a work in progress, and you probably want to use a tagged release version. Version 3 breaking changes I

null 3.1k Jun 25, 2022
A simple to use, composable, command line parser for C++ 11 and beyond

Lyra A simple to use, composing, header only, command line arguments parser for C++ 11 and beyond. Obtain License Standards Stats Tests License Distri

Build Frameworks Group 342 Jun 16, 2022