Hi!

I wrote this manpage for qbe(1) while helping to get qbe into Debian. I
figured that you could be interested in maintaining it upstream, so that
other distros can package it as well.

If that's not the case, just ignore this :^)

---
 Makefile  |  3 +++
 doc/qbe.1 | 25 +++++++++++++++++++++++++
 2 files changed, 28 insertions(+)
 create mode 100644 doc/qbe.1

diff --git a/Makefile b/Makefile
index 2482eb1..72cd178 100644
--- a/Makefile
+++ b/Makefile
@@ -58,9 +58,12 @@ config.h:
 install: qbe
 	mkdir -p "$(DESTDIR)$(BINDIR)"
 	install -m755 qbe "$(DESTDIR)$(BINDIR)/qbe"
+	mkdir -p "$(DESTDIR)$(PREFIX)/share/man/man1"
+	install -m644 doc/qbe.1 "$(DESTDIR)$(PREFIX)/share/man/man1/"
 
 uninstall:
 	rm -f "$(DESTDIR)$(BINDIR)/qbe"
+	rm -f "$(DESTDIR)$(PREFIX)/share/man/man1/qbe.1"
 
 clean:
 	rm -f *.o */*.o qbe
diff --git a/doc/qbe.1 b/doc/qbe.1
new file mode 100644
index 0000000..e231175
--- /dev/null
+++ b/doc/qbe.1
@@ -0,0 +1,25 @@
+.Dd $Mdocdate: April 10 2024 $
+.Dt QBE 1
+.Os
+.Sh NAME
+.Nm qbe
+.Nd small embeddable C compiler backend
+.Sh SYNOPSIS
+.Nm
+.Op Fl h
+.Op Fl o Ar file
+.Op Fl t Ar target
+.Op Fl d Ar flags
+.Op Ar file.ssa | Fl
+.Sh DESCRIPTION
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl h
+Prints the help message and exits.
+.It Fl o Ar file
+Output to file.
+.It Fl t Ar target
+Generate for a target among: amd64_sysv (default), amd64_apple, arm64, arm64_apple, riscv.
+.It Fl d Ar flags
+Dump debug information.
+.El
-- 
2.43.0

On 2024-04-28 at 21:07-03:00, Guilherme Puida wrote:
> +The options are as follows:

I wonder if help2man is net-beneficial in this case.
It would be an (optional) dependency to build the man page,
but make sure the option descriptions are in sync,
and allow for other additional sections to be easier to write:
https://www.gnu.org/software/help2man#Including-text

On 30/04/2024 02:44, Nguyễn Gia Phong wrote:
> I wonder if help2man is net-beneficial in this case.

There is also [scdoc][1] for simple, human-written man pages.

[1]: https://git.sr.ht/~sircmpwn/scdoc

On 2024-04-30 at 10:08+02:00, Jonne Ransijn wrote:
> On 30/04/2024 02:44, Nguyễn Gia Phong wrote:
> > I wonder if help2man is net-beneficial in this case.
> > It would [...] make sure the option descriptions are in sync
>
> There is also [scdoc][1] for simple, human-written man pages.
>
> [1]: https://git.sr.ht/~sircmpwn/scdoc

To clarify, help2man would take synposis, description and options
from e.g. qbe -h, although qbe help string needs to be tweaked a bit
to conform with the expected format to get the precise section name:

-qbe [OPTIONS] {file.ssa, -}
+Usage: qbe [OPTIONS] {file.ssa, -}
+
+Compile QBE intermediate language into assembly.
+
+Options:
 	-h          prints this help

Test with something like the following
(help2man expects --help and --version by default)

man <(help2man qbe --help-option=-h --version-string=1.2 --no-info)

On Tue, Apr 30, 2024 at 09:44:53AM +0900, Nguyễn Gia Phong wrote:
> I wonder if help2man is net-beneficial in this case.
> It would be an (optional) dependency to build the man page,
> but make sure the option descriptions are in sync,
> and allow for other additional sections to be easier to write:
> https://www.gnu.org/software/help2man#Including-text

I think I tried to use help2man and found the output not very good in
this situation.

I know that maintaining a pure roff man page can be somewhat difficult,
so I'm up to changing this to use help2man, scdoc or some other tool.
Just let me know if that's the case.

By the way, I think my email client is misconfigured, so please CC me
when discussing this :^)

--puida

If that's needed to get into debian, we can maintain
a manpage written in troff.

On Fri, May 03, 2024 at 10:14:31PM +0200, Quentin Carbonneaux wrote:
> If that's needed to get into debian, we can maintain
> a manpage written in troff.

Troff was just what I chose when writing the manpage. Using other tools
won't impact the Debian package at all, so go for it if it makes your
life easier (I don't have the time to rewrite it using anything else
right now, though).

By the way, qbe is in the NEW queue right now [1], and should hit the
unstable archives soon.

[1]: https://ftp-master.debian.org/new.html

--puida

On Fri, May 03, 2024 at 10:14:31PM +0200, Quentin Carbonneaux wrote:
> If that's needed to get into debian, we can maintain
> a manpage written in troff.

I am used to write man pages using the man macros. If needed I can help
about this topic (please, don't ask me about mandoc macros ...).

Regards,