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.

[emmatebibyte]

Sorry for the delay in my response, I have been experiencing a number of life changes and became swamped with responsibilities.

I have been hacking on the new man page, fixing what I see as deficiencies in the technical tone of the writing and in the automatically generated roff.

I dislike the use of a roff generator as it creates non-standard and ugly roff, so I’m currently working to update the man page to more readable, standard, and useful roff syntax.

[emmatebibyte]

If you like the changes I make, feel free to use them. If you don’t, feel free not to. I understand that I am late to the party here :)

[emmatebibyte]

The patchfile containing nitpicks about tone, vocabulary, precision, and formatting:

1,2c1
< .\" Text automatically generated by txt2man
< .TH PDPMAKE 1 "14 June 2024" "Ron Yorston" "Usage Manual"
---
> .TH PDPMAKE 1 "18 June 2024" "Ron Yorston" "Usage Manual"
4,5c3,4
< \fBpdpmake \fP- Public domain POSIX make
< \fB
---
> .B pdpmake
> \(en public domain POSIX make
7,15c6,19
< .nf
< .fam C
< \fBpdpmake\fP [\fB--posix\fP] [\fB-ehiknpqrSst\fP] [\fB-C\fP \fIdir\fP] [\fB-f\fP \fImkfile\fP] [\fB-j\fP \fInum_jobs\fP]
<         [\fB-x\fP \fIpragma\fP] [\fImacro\fP[:[:[:]]]=\fIvalue\fP \.\.\.] [\fItarget\fP \.\.\.]
< 
< .fam T
< .fi
< .fam T
< .fi
---
> 
> \fBpdpmake\fP
> .RB [ --posix ]
> .RB [ -ehiknpqrSst ]
> .RB [ -C
> .IR dir ]
> .RB [ -f
> .IR file ]
> .RB [ -j
> .IR num_jobs ]
> .RB [ -x \ \fIpragma\fP]
> .RI [ macro [:[:[:]]]= value \0...]
> .RI [ target \0...]
> 
17,22c21,29
< The \fBpdpmake\fP utility creates or updates files following a set of rules.
< The created or updated files, called targets, are typically derived from
< other files, called prerequisites. Targets are derived according to
< rules describing file dependencies and listing commands to be executed.
< Rules may be inferred by the utility or explicitly defined in one or
< more makefiles.
---
> 
> The
> .B pdpmake
> utility creates or updates files following a set of rules. The created or
> updated files, called targets, are typically derived from other files, called
> prerequisites. Targets are described by rules which list commands to be
> executed. Rules may be inferred by the utility or explicitly defined in one or
> more files. A target may also depend on other targets, whose rules must be
> executed before its. Files which contain these targets are known as makefiles.
24,44c31,54
< .TP
< .B
< \fB-C\fP \fIdir\fP
< Change to \fIdir\fP before reading the makefiles or doing anything
< else. If multiple \fB-C\fP options are specified, each is
< interpreted relative to the previous one: '\fB-C\fP / \fB-C\fP etc' is
< equivalent to '\fB-C\fP /etc'.
< .TP
< .B
< \fB-e\fP
< Let environment variables override macro assignments within
< makefiles.
< .TP
< .B
< \fB-f\fP \fImkfile\fP
< Specify a different makefile. The argument \fImkfile\fP may be
< a path to a file, or a minus sign '-' for standard input.
< Multiple files may be specified and are read in that order.
< .TP
< .B
< \fB-h\fP
---
> 
> .IP \fB--posix\fP
> Enable strict POSIX-compliant mode. This option must be the first given on the
> command line.
> .IP \fB-C\fP\ \fIdir\fP
> Before execution, switch to
> .IR dir .
> If specified multiple times, each invocation is interpreted relative to the
> previous one:
> \(oq\fB-C\fP
> /
> .B -C
> etc\(cq is equivalent to
> \(oq\fB-C\fP /etc\(cq.
> .IP \fB-e\fP
> Allow environment variables to override macro assignments.
> .IP \fB-f\fP\ \fIfile\fP
> Specify a makefile
> .I file
> from which to read. If invoked multiple times, specified files are read in order
> of invocation. See
> .B INPUT FILES
> section.
> .IP \fB-h\fP
46,84c56,75
< .TP
< .B
< \fB-i\fP
< Ignore non-zero exit codes returned by commands executed
< to rebuild files. This is equivalent to using the special
< target \fB.IGNORE\fP without prerequisites.
< .TP
< .B
< \fB-j\fP \fInum_jobs\fP
< Unused, provided only for compatibility.
< .TP
< .B
< \fB-k\fP
< Continue processing after errors are encountered, but only for
< targets that don't depend on the target whose creation
< caused the error.
< .TP
< .B
< \fB-n\fP
< Print commands that would have been executed, but don't
< actually execute them unless the command is prefixed with '+'.
< .TP
< .B
< \fB-p\fP
< Print the macro definitions and rules that result from reading
< the makefiles, then continue with any processing required.
< .TP
< .B
< \fB--posix\fP
< Enable strict POSIX-compliant mode.
< This option must be the first given on the command line.
< .TP
< .B
< \fB-q\fP
< Do  not  execute  any commands, instead exit 0 if the specified
< targets are up to date, and 1 otherwise.
< .TP
< .B
< \fB-r\fP
---
> .IP \fB-i\fP
> If commands in rules exit unsuccessfully, ignore them and continue. This
> option is equivalent to specifying the special target
> .B .IGNORE
> without prerequisites.
> .IP \fB-j\fP\ \fInum_jobs\fP
> Ignored. Exists for compatibility with other
> .BR make (1)
> implementations.
> .IP \fB-k\fP
> If an error is encountered, continue processing rules. Recipes for targets which
> depend on other targets that have caused errors are not executed.
> .IP \fB-n\fP
> Print without executing commands that are not prefixed with \(oq+\(cq.
> .IP \fB-p\fP
> Print macro definitions and rules during execution.
> .IP \fB-q\fP
> If specified targets are up to date, exit successfully. Otherwise, exit with an
> error code of 1. Do not execute any rules.
> .IP \fB-r\fP
86,115c77,110
< .TP
< .B
< \fB-S\fP
< Stop processing if an error is encountered. This is the default
< behaviour and the opposite of \fB-k\fP.
< .TP
< .B
< \fB-s\fP
< Do not print the commands as they are executed. This is
< equivalent to using the special target \fB.SILENT\fP without
< prerequisites.
< .TP
< .B
< \fB-t\fP
< Touch files instead of running the commands required to build
< them, but not for targets that have no commands or that are
< already up-to-date.
< .TP
< .B
< \fB-x\fP \fIpragma\fP
< Allow certain \fBpdpmake\fP extensions to apply in strict
< POSIX-compliant mode. For a list of supported pragmas
< see \fBPRAGMAS\fP below. Multiple \fB-x\fP options can be given.
< .TP
< .B
< \fImacro\fP[:[:[:]]]=\fIvalue\fP
< Assign \fIvalue\fP to \fImacro\fP, overriding
< the value of \fImacro\fP in the makefile, if it exists.
< Macro assignments and targets may be mixed on the command line.
< All assignments will be processed first, then the targets.
---
> .IP \fB-S\fP
> Stop processing if an error is encountered. This is the default behaviour and
> the opposite of
> .BR -k .
> .IP \fB-s\fP
> Do not print commands as they are executed. This is equivalent to using the
> special target
> .B .SILENT
> without prerequisites.
> .IP \fB-t\fP
> Instead of executing rules, touch target files. Ignores targets that are
> up-to-date or those which have no rules specified.
> .IP \fB-x\fP\ \fIpragma\fP
> Allow certain extensions when using strict POSIX-compliant mode. For a list of
> supported pragmas, see the
> .B PRAGMAS
> section. This option may be specified more than once to utilize multiple
> extensions.
> .IP \fImacro\fP[:[:[:]]]=\fIvalue\fP
> Assign
> .I value
> to
> .IR macro ,
> overriding the value of
> .I macro
> in the input if it exists. Macro assignments and targets may be mixed on the
> command line. Assignments will be processed before targets.
> .SH INPUT FILES
> 
> If an input makefile is unspecified, the working directory will be searched for
> a file named either \(oqmakefile\(cq or \(oqMakefile\(cq, the former taking
> priority over the latter.
> 
> If the input file is \(oq-\(cq, the standard input shall be used as the input.
117,185c112,157
< .TP
< .B
< macro_name
< Allow '-' as a valid character in macro names.
< .TP
< .B
< target_name
< Allow '-' and '/' as valid characters in target names.
< .TP
< .B
< command_comment
< Don't treat the '#' character as introducing a comment
< in commands or in target and inference rules.
< .TP
< .B
< empty_suffix
< Permit an empty suffix in macro expansions of the form
< $(VAR:=.c).
< .TP
< .B
< posix_2017
< Enforce the old POSIX 2017 standard.
< .TP
< .B
< posix_2024
< Enforce the current POSIX 2024 standard. In this case
< the \fBmacro_name\fP and \fBtarget_name\fP pragmas aren't
< required as the 2024 standard allows the additional
< characters.
< .TP
< .B
< posix_202x
< An alias for posix_2024.
< .TP
< .B
< windows
< Allow target names of the form C:/path in builds for
< Microsoft Windows. This may also require setting
< \fBtarget_name\fP.
< .SH EXTENDED DESCRIPTION
< 
< \fBpdpmake\fP is a make utility following the POSIX standard:
< \fIhttps://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html\fP
< .PP
< The behavior of the utility should match the behavior described in the
< POSIX standard specification, while allowing a set of extensions for
< convenience. The behavior may be fine-tuned using command line options,
< environment variables, or special targets defined inside makefiles.
< .PP
< By default \fBpdpmake\fP allows all extensions. To disable all extensions and
< enable strict POSIX-compliant mode, do any of the following:
< .RS
< .IP \(bu 3
< Add the special target \fB.POSIX\fP as the first non-comment
< line in the first makefile to be processed. This is the standard
< approach for declaring a makefile to be POSIX-compliant.
< .IP \(bu 3
< Add the \fB--posix\fP flag as the first command line option given to
< \fBpdpmake\fP. This flag is unique to \fBpdpmake\fP and may not be available
< in other make utilities.
< .IP \(bu 3
< Set the \fBPDPMAKE_POSIXLY_CORRECT\fP environment variable
< to any value. This environment variable is unique to \fBpdpmake\fP
< and may not be available in other make utilities.
< .RE
< .PP
< While in strict POSIX-compliant mode, you may selectively enable certain
< extensions through the use of pragmas (see \fBPRAGMAS\fP).
< To use one or more pragmas, do any of the following:
---
> 
> While in strict POSIX-compliant mode, pragmas may be utilized to selectively
> enable certain extensions.
> 
> .IP \fBmacro_name\fP
> Allow \(oq-\(cq in macro names.
> .IP \fBtarget_name\fP
> Allow \(oq-\(cq and \(oq/\(cq in target names.
> .IP \fBcommand_comment\fP
> Don't treat the \(oq#\(cq character as introducing a comment in commands or in
> target and inference rules.
> .IP \fBempty_suffix\fP
> Permit an empty suffix in macro expansions. This takes the form of $(VAR:=.c).
> .IP \fBposix_2017\fP
> Enforce the old POSIX.1-2017 standard.
> .IP \fBposix_2024\fP
> Enforce the current POSIX.1-2024 standard. In this case the
> .B macro_name
> and
> .B target_name
> pragmas aren\(cqt required as this standard allows these additional characters.
> .IP \fBposix_202x\fP
> An alias for the
> .B posix_2024
> pragma.
> .IP \fBwindows\fP
> Allow Microsoft Windows-style paths as target names. This may also require
> specifying the
> .B target_name
> pragma.
> .SH STANDARDS
> 
> This utility follows the
> .I Section 12.2, Utility Syntax Guidelines
> of the POSIX.1-2024 standard for the
> .B make
> utility.
> 
> The behavior in this utility should match the behavior described in this
> section but also includes a set of extensions. Its behavior may be fine-tuned
> using command line options, environment variables, or special targets. See the
> .B PRAGMAS
> section.
> 
> By default, all extensions are enabled. The following list contains all of the
> methods for disabling all extensions and enabling strict POSIX-compliant mode:
188,195c160,181
< Add \fB-x\fP \fIpragma\fP as a command line option given to \fBpdpmake\fP.
< Multiple \fB-x\fP options can be given. This flag is unique to \fBpdpmake\fP
< and may not be available in other make utilities.
< .IP \(bu 3
< Add the special target \fB.PRAGMA:\fP \fIpragma\fP to the first
< makefile to be processed. Multiple pragmas can be specified.
< This special target is unique to \fBpdpmake\fP and may not be available
< in other make utilities.
---
> Add the special target
> .B .POSIX
> as the first non-comment line in the first input to be processed. This is the
> standard approach for declaring a makefile to be POSIX-compliant.
> .IP \(bu 3
> Add the
> .B --posix
> flag as the first command line option given to
> .BR pdpmake .\ This
> flag is unique to
> .B pdpmake
> and may not be available in other
> .BR make (1)
> implementations.
> .IP \(bu 3
> Set the
> .B PDPMAKE_POSIXLY_CORRECT
> environment variable to any value. This environment variable is unique to
> .B pdpmake
> and may not be available in other
> .BR make (1)
> implementations.
197,199c183,187
< .PP
< \fBpdpmake\fP implements a set of extensions to the POSIX standard. These may
< be compatible with other make utilities. The available extensions are:
---
> 
> A set of extensions to the POSIX standard are implemented for this
> utility. These may be compatible with other
> .BR make (1)
> implementations. The available extensions are:
202,208c190,203
< The \fB-C\fP directory command line option changes the current
< working directory.
< .IP \(bu 3
< Double colon rules are allowed.
< .IP \(bu 3
< The following conditional keywords are allowed: ifdef, ifndef,
< ifeq, ifneq, else, endif
---
> The
> .B -C
> directory command line option changes the current working directory.
> .IP \(bu 3
> Double-colon rules are allowed.
> .IP \(bu 3
> The conditional keywords
> .BR ifdef ,
> .BR ifndef ,
> .BR ifeq ,
> .BR ifneq ,
> .BR else ,\ and
> .B endif
> are implemented.
211,214c206
< \fBlib.a\fP(mem1.o mem2.o\.\.\.).
< .IP \(bu 3
< The macro assignment := is permitted. It is equivalent to ::=
< in POSIX.
---
> .BR lib.a (mem1.o\ mem2.o...).
216,219c208,223
< Chained inference rules can be used when searching for the
< prerequisites of a target. Thus, if there are inference rules
< \fI.p.q\fP and \fI.q.r\fP and the file \fIthing.p\fP exists,
< make is able to deduce how to create \fIthing.r\fP.
---
> The macro assignment operator
> .B :=
> is implemented. It is equivalent to the POSIX-specified
> .BR ::=
> macro assignment operator.
> .IP \(bu 3
> Chained inference rules can be used when searching for the prerequisites of a
> target. This means that if there are inference rules
> .I .p.q
> and
> .I .q.r
> and the file
> .I thing.p
> exists, the method by which the file
> .I thing.r
> is created can be deduced.
221c225
< The wildcards '*', '?' and '[]' can be used in the targets
---
> The wildcards \(oq*\(cq, \(oq?\(cq and \(oq[]\(cq can be used in the targets
224,226c228,230
< The '#' character on a command line or in a macro expansion
< doesn't indicate the start of a comment. In other locations '#'
< can be escaped by preceding it with a backslash.
---
> The \(oq#\(cq character on a command line or in a macro expansion doesn\(cqt
> indicate the start of a comment. In other locations, \(oq#\(cq can be escaped by
> preceding it with a backslash.
229c233,234
< $? is expanded.
---
> .B $?
> is expanded.
231,232c236,240
< An \fBinclude\fP line with no files specified is silently ignored.
< At least one blank must follow the \fBinclude\fP for the line to
---
> An
> .B include
> line with no files specified is silently ignored. At least one blank must follow
> the
> .B include for the line to
235,236c243,254
< The shell used to process build commands isn't started with
< the \fB-e\fP option when errors aren't being ignored.
---
> The shell used to process build commands isn\(cqt started with the
> .B -e
> option when errors aren\(cqt being ignored.
> .IP \(bu 3
> Macro definitions and targets may be mixed on the command line. The macro
> definitions are processed first, then the targets.
> .IP \(bu 3
> The
> .B $<
> and
> .B $*
> internal macros are given values in target rules.
238,243c256
< Macro definitions and targets may be mixed on the command line.
< The macro definitions are processed first, then the targets.
< .IP \(bu 3
< The $< and $* internal macros are given values in target rules.
< .IP \(bu 3
< When a build command receives a signal the target is removed.
---
> When a build command receives a signal, the target is removed.
245,246c258,259
< .PP
< The following features were added in the POSIX 2024 standard:
---
> 
> The following implementation details apply only to the POSIX.1-2024 standard:
249c262
< Nested macro expansion. e.g. $(FOO$(BAR))
---
> Nested macro expansion syntax: $(FOO$(BAR))
251,252c264,266
< Prerequisites of the \fB.PHONY\fP special target are always
< treated as being out-of-date.
---
> Prerequisites of the
> .B .PHONY
> special target are always considered out-of-date.
256,257c270,275
< Missing include files can be ignored by using \fB-include\fP \fIfile\fP
< instead of \fBinclude\fP \fIfile\fP.
---
> Missing include files can be ignored by using
> .B -include
> .I file
> instead of
> .B include
> .IR file .
262,279c280,314
< The $^ and $+ internal macros evaluate to all prerequisites of the
< current target (not just out-of-date ones, as with $?). $^ removes
< duplicated prerequisites from the list, $+ doesn't.
< .IP \(bu 3
< If no \fBMAKE\fP environment variable is provided the \fBMAKE\fP
< macro is initialised from argv[0], with a relative path converted
< to absolute.
< .IP \(bu 3
< The macro assignments ::=, :::=, +=, ?= and != are permitted.
< .IP \(bu 3
< Pattern macros extend the standard suffix substitution in macro
< expansion to allow changes to prefixes as well.
< .IP \(bu 3
< An escaped newline within a macro expansion on a command line
< is replaced by a space.
< .IP \(bu 3
< The \fBCURDIR\fP macro is set to the current directory during
< program start up.
---
> The
> .B $^
> and
> .B $+
> internal macros evaluate to all prerequisites of the current target (not just
> out-of-date ones, as with
> .BR $?).
> .B $^
> removes duplicated prerequisites from the list,
> .B $+
> doesn\(cqt.
> .IP \(bu 3
> If no
> .B MAKE
> environment variable is provided the
> .B MAKE
> macro is initialised from argv[0], with a relative path converted to absolute.
> .IP \(bu 3
> The
> .BR ::= ,
> .BR :::= ,
> .BR += ,
> .BR ?= ,
> and
> .BR !=
> macro assignments.
> .IP \(bu 3
> Pattern macros extend the standard suffix substitution in macro expansion to
> allow changes to prefixes.
> .IP \(bu 3
> An escaped newline within a macro expansion in a rule is replaced by a space.
> .IP \(bu 3
> The
> .B CURDIR
> macro is set to the current directory during program start up.
281c316,321
< \fBpdpmake\fP is in the public domain. See \fIhttps://unlicense.org\fP
---
> 
> .B pdpmake
> is free and unencumbered software released into the public domain. See
> <https://unlicense.org>.
> .SH SEE ALSO
> .BR make (1p)

[rmyorston]

@emmatebibyte Thanks for your patch to the man page. I've applied it without any changes.

[emmatebibyte]

On June 20, 2024 2:49:25 PM UTC, Ron Yorston @.***> wrote:

@emmatebibyte Thanks for your patch to the man page. I've applied it without any changes.

Should the Makefile be updated to also install the manpage?

-- Emma Tebibyte (fae/faer) http://tebibyte.media/~emma

[rmyorston]

Should the Makefile be updated to also install the manpage?

Certainly.