Manual page?

[emmatebibyte]

Could there be a manpage made? I could take a crack at it if it’s desired

[rmyorston]

A manpage would be a most welcome addition. Any contribution would be gratefully received.

[absolutelynothinghere]

I'm also interested in a manual for pdpmake so I went ahead and wrote one, see below.

This manual is written in a subset of ronn-format which is very similar to markdown, and can be converted to standard roff format using ruby-ronn or my own ronn2roff.sh script. Most of the option descriptions were copied from the POSIX make specification with minimal edits for clarity. Feel free to make any necessary changes.

Downloads: pdpmake.ronn, pdpmake.1

pdpmake(1) -- Public domain POSIX make
======================================

## SYNOPSIS

`pdpmake` [<OPTION>...] [-f <MAKEFILE>] [<TARGET>...]

## OPTIONS

  * `-C` <PATH>:
    Change the current directory to <PATH> before running pdpmake.

  * `-e`:
    Cause environment variables, including those with null values,
    to override macro assignments within makefiles.

  * `-f` <MAKEFILE>:
    Specify a different makefile. The argument <MAKEFILE> may be
    a path to a file, or a minus sign '-' for standard input.
    There can be multiple instances of this option, and they shall
    be processed in the order specified.

  * `-i`:
    Ignore error codes returned by invoked commands.
    This mode is the same as if the special target `.IGNORE`
    were specified without prerequisites.

  * `-j` <MAXJOBS>:
    Unused option, provided only for compatibility.

  * `-k`:
    Continue to update other targets that do not depend on
    the current target if a non-ignored error occurs while
    executing the commands to bring a target up-to-date.

  * `-n`:
    Write commands that would be executed on standard output,
    but do not execute them. However, commands with a plus sign
    '+' prefix shall be executed. In this mode, commands with an
    at sign '@' prefix shall be written to standard output.

  * `-p`:
    Write to standard output the complete set of macro definitions
    and target descriptions.

  * `--posix`:
    Enable strict POSIX-compliant mode.
    This option must be the first given on the command line.

  * `-q`:
    Return a zero exit value if the target file is up-to-date;
    otherwise, return an exit value of 1.
    Targets shall not be updated if this option is specified.
    However, commands with a plus sign '+' prefix shall be executed.

  * `-r`:
    Clear the suffix list and do not use the built-in rules.

  * `-S`:
    Terminate pdpmake if an error occurs while executing the
    commands to bring a target up-to-date.
    This shall be the default and the opposite of `-k`.

  * `-s`:
    Do not write makefile commands or touch messages (see `-t`)
    to standard output before executing.

  * `-t`:
    Update the modification time of each target as though a
    'touch <TARGET>' had been executed.
    Targets that have prerequisites but no commands, or that
    are already up-to-date, shall not be touched in this manner.
    Write messages to standard output for each target file
    indicating the name of the file and that it was touched.
    Normally, the makefile commands associated with each target are
    not executed. However, a command with a plus sign '+' prefix
    shall be executed.

  * `-x` <PRAGMA> [`-x` <PRAGMA>] ...:
    Allow extension <PRAGMA> while in strict POSIX-compliant mode.
    For a list of supported extensions, see <PRAGMAS> below.

  * <MACRO>=<VALUE>:
    Assign <VALUE> to <MACRO>, overriding the value of <MACRO>
    in the makefile, if it exists. Macro assignments must be given
    before targets on the command line.

## PRAGMAS

  * `macro_name`:
    Allow '-' as a valid character in macro names.

  * `target_name`:
    Allow '-' and '/' as a valid characters in target names.

  * `command_comment`:
    Don't treat the '#' character as introducing a comment
    in commands or in target and inference rules.

  * `empty_suffix`:
    Permit an empty suffix in macro expansions of the form
    `$(VAR:=.c)`.

  * `posix_202x`:
    Enforce the future POSIX 202X standard rather than the current
    POSIX 2017. In this case the `macro_name` and `target_name`
    pragmas aren't required as the future standard will allow
    the additional characters.

## COPYRIGHT

Copyright (C) Ron Yorston

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or
distribute this software, either in source code form or as a compiled
binary, for any purpose, commercial or non-commercial, and by any
means.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

Unlicense: <https://unlicense.org>

[rmyorston]

@absolutelynothinghere Thanks for getting us started with a man page!

It caused me to think more seriously about what I'd like to see in a man page for pdpmake.

I'm not too keen on copying text from POSIX:

• Standards bodies are a bit fussy about their intellectual property. (Fedora Linux has removed the POSIX man pages due to licensing problems.)
• The terminology is rather more formal and the descriptions more exact than I'd like.

So I copied text from bmake and GNU make instead, and knocked it about a bit.

I didn't like that the man page had hard-coded line breaks so it didn't adjust to terminal width. In the past I've used txt2man so I reformatted the source to suit. (It has its down sides too, though: some hard-coded formatting was necessary.)

I took out the copyright section because it didn't seem entirely necessary. And added the shiny new posix_2017 pragma.

Results are pdpmake.txt and pdpmake.1.txt. The command to get from one to the other is:

   txt2man -t PDPMAKE -s 1 pdpmake.txt >pdpmake.1

All it needs is another 1500 lines of DESCRIPTION and EXTENDED DESCRIPTION and it'll be good to go ;-)

[absolutelynothinghere]

Thanks for getting us started with a man page!

Thank you for developing pdpmake :) I'm happy to help.

I took out the copyright section because it didn't seem entirely necessary.

The copyright section is a standard one, and it's important for pdpmake because it explicitly dedicates the package to the public domain. In some situations a missing copyright statement implies all rights reserved, the words "public domain" alone are not enough because it's possible to modify public domain material and re-license it under a different license... I would suggest at least mentioning the license name (Unlicense) in the manual.

And added the shiny new posix_2017 pragma.

That's great news. Is there anywhere I can access the full pdpmake changelog?

All it needs is another 1500 lines of DESCRIPTION and EXTENDED DESCRIPTION and it'll be good to go ;-)

Here's the DESCRIPTION section, written from scratch this time: pdpmake.txt

I also added the -h flag to the list and tidied up the spacing. As for the EXTENDED DESCRIPTION section, I've rarely seen it in manual pages so it's probably safe to ignore, for now.

[rmyorston]

Is there anywhere I can access the full pdpmake changelog?

I don't maintain a changelog. There's the git history, obviously, and I have some release notes on my website. These summarise changes since the previous release.

Thanks for the DESCRIPTION section, looks good. Although EXTENDED DESCRIPTION isn't very common it appears in all POSIX man pages (along with other useful material in APPLICATION USAGE and EXAMPLES). bmake has a similar amount of detailed information in their man page. GNU make shuffles most of it off into 'info' documents, which I rarely look at.

The extent of the information provided in the EXTENDED DESCRIPTION is the main reason I kept putting off writing a man page. I suppose if we can refer to the POSIX man page it would only be necessary to describe the non-POSIX extensions in our man page.

I also added the -h flag

But there isn't an -h flag! Any unused flag will cause the usage message to be printed. (I generally use -? for that purpose.)

Thinking about that sent me off on a tangent: it's possible to include information about the build-time configuration in the help message. For the default configuration this now reports:

$ pdpmake -?
pdpmake: invalid option -- '?'
Usage: pdpmake [--posix] [-C path] [-f makefile] [-j num] [-x pragma]
	 [-eiknpqrsSt] [macro[::]=val ...] [target ...]

This build supports: non-POSIX extensions, POSIX 202X, POSIX 2017
In strict POSIX mode the 2017 standard is enforced by default.

For a build without any extensions (-DENABLE_FEATURE_MAKE_EXTENSIONS=0) it can even point to the POSIX man page which should precisely document the resulting binary:

$ pdpmake -?
pdpmake: invalid option -- '?'
Usage: pdpmake [-f makefile] [-eiknpqrsSt] [macro=val ...] [target ...]

This build supports: POSIX 2017

For details see:
  https://pubs.opengroup.org/onlinepubs/9699919799/utilities.2018edition/make.html

[absolutelynothinghere]

But there isn't an -h flag! Any unused flag will cause the usage message to be printed.

Hah, I didn't know that. A help flag would be nice to have, it could show the build-time configuration as you mentioned, as well as the program version.

I suppose if we can refer to the POSIX man page it would only be necessary to describe the non-POSIX extensions in our man page.

Agreed. Let's focus on the pdpmake-specific features in the manual.

I wrote the EXTENDED DESCRIPTION section and moved the POSIX standard link to it.
Here's the updated manual: pdpmake.txt

[rmyorston]

This is developing very nicely! Thank you.

A question arises: what should be shipped? Just the man page, the man page and the text file, or just the text file? If the text file is shipped there could be a target in the Makefile to generate the man page.

Opinions?

[absolutelynothinghere]

A question arises: what should be shipped?

I suggest shipping both text file and manual. Having a manual page ready even before compilation is helpful, and the text file can act as fallback.

As an aside; I prefer not adding extra dependencies during compilation, especially in regards to txt2man as it depends on GNU tools, those may not be available on bare bones / bootstrapped system where pdpmake is most likely to be used. I personally don't mind using txt2man but I don't expect users to have it.

[rmyorston]

I don't expect users to have it.

Nor do I. The plan would be to have a separate target which would require an explicit invocation of make pdpmake.1. It wouldn't be triggered by a compilation.

pdpmake.1: pdpmake.txt
	@txt2man -t PDPMAKE -s 1 pdpmake.txt >pdpmake.1

It's useful as documentation of the options required.

I'd be happy to take pdpmake.txt as it stands now. Would you care to raise a pull request?

[rmyorston]

OK, I've merged your pull request. Thanks!

I'm currently working through a few POSIX 202X issues I've spotted. These will require some changes to the man page. It'll be easier for me to handle them myself, as I go, rather than trouble you with them.

[absolutelynothinghere]

Great, thank you!

I don't mind helping out with the changes if I have time, I mostly paraphrase from the pdpmake homepage / release notes anyway.

[rmyorston]

The code moves more quickly than the homepage/release notes. It now has a -h option, so the man page was able to predict the future. Spooky!

[ale5000-git]

@rmyorston
Is there a downloadable manual of make usable with man of busybox?

Like this:
busybox man pdpmake

[rmyorston]

@ale5000-git
No, there isn't a man page suitable for use with busybox-w32. I'll need to consider whether there should be and if so how to handle it.

In the meantime I was able to generate a pre-formatted man page on my Linux system by running the following command on the man page in this repo:

man ./pdpmake.1 | sed -e 's/•/*/g' -e 's/‐/-/g' >pdpmake.cat

The sed converts some UTF-8 characters to something Windows can handle.

Here it is: pdpmake.cat.txt

[ale5000-git]

Thanks it works, there is only one issue with this char: ’
but I have fixed it manually.