Writing Manpage #5391

New Issue

GiteaMirror · 2025-11-02T06:23:18-06:00

GiteaMirror commented

2025-11-02 06:23:18 -06:00

Originally created by @bagasme on GitHub (May 13, 2020).

Description

It is convenient to have manpage for viewing Gitea docs (especially Command Line and Config Cheat Sheet) locally.

The manpage will be written using go-md2man as suggested by @lafriks.

The workflow (as described in Hacking doc should be modified to include that any changes to config cheat sheet and/or command line options list docs above, the corresponding changes should also be made onto manpage.

However, how should the manpage be distributed along with Gitea? Currently dl page distribute Gitea as single binary and xz-compressed of it. So I had two options:

Distribute manpage separately, as xz-compressed, or
For compressed archive of Gitea binary, throw manpage into it.

Originally created by @bagasme on GitHub (May 13, 2020). ## Description It is convenient to have manpage for viewing Gitea docs (especially [Command Line](https://docs.gitea.io/en-us/command-line/) and [Config Cheat Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/)) locally. The manpage will be written using go-md2man as suggested by @lafriks. The workflow (as described in [Hacking doc](https://docs.gitea.io/en-us/hacking-on-gitea/) should be modified to include that any changes to config cheat sheet and/or command line options list docs above, the corresponding changes should also be made onto manpage. However, how should the manpage be distributed along with Gitea? Currently [dl page](https://dl.gitea.io/gitea) distribute Gitea as single binary and xz-compressed of it. So I had two options: 1. Distribute manpage separately, as xz-compressed, or 2. For compressed archive of Gitea binary, throw manpage into it.

GiteaMirror added the issue/confirmed type/docs labels 2025-11-02 06:23:18 -06:00

GiteaMirror closed this issue

2025-11-02 06:23:19 -06:00

GiteaMirror commented

2025-11-02 06:23:19 -06:00

@techknowlogick commented on GitHub (May 13, 2020):

I believe that https://github.com/urfave/cli the CLI library we use is able to auto generate man pages.

@techknowlogick commented on GitHub (May 13, 2020): I believe that https://github.com/urfave/cli the CLI library we use is able to auto generate man pages.

GiteaMirror commented

2025-11-02 06:23:20 -06:00

@lafriks commented on GitHub (May 13, 2020):

I think it uses https://github.com/cpuguy83/go-md2man/

@lafriks commented on GitHub (May 13, 2020): I think it uses https://github.com/cpuguy83/go-md2man/

GiteaMirror commented

2025-11-02 06:23:20 -06:00

@bagasme commented on GitHub (May 14, 2020):

@techknowlogick i don't see manpage generation on cli docs

@bagasme commented on GitHub (May 14, 2020): @techknowlogick i don't see manpage generation on [cli docs](https://github.com/urfave/cli/blob/master/docs/v2/manual.md)

GiteaMirror commented

2025-11-02 06:23:20 -06:00

@techknowlogick commented on GitHub (May 14, 2020):

Not in manual, but here is a code reference: 841e5b03ad/docs.go (L24)

@techknowlogick commented on GitHub (May 14, 2020): Not in manual, but here is a code reference: https://github.com/urfave/cli/blob/841e5b03ad972b9578bb8ad73441e9d9a51d3c14/docs.go#L24

GiteaMirror commented

2025-11-02 06:23:20 -06:00

@silverwind commented on GitHub (May 24, 2020):

I see that https://github.com/go-gitea/gitea/pull/11476 adds 2 more markdown source files and I'm not happy about it because if I understand correctly it would require us to change 4 files for each change in the config. Also I think manpage is geared more towards command arguments and should probably only cover those, ideally also not duplicating with --help.

The existing duplication of the config file and the hacking page is already an issue because they constantly get out of sync. I think we should work on something that generates everything from one single source file, maybe in parsable a format like YAML.

@silverwind commented on GitHub (May 24, 2020): I see that https://github.com/go-gitea/gitea/pull/11476 adds 2 more markdown source files and I'm not happy about it because if I understand correctly it would require us to change 4 files for each change in the config. Also I think manpage is geared more towards command arguments and should probably only cover those, ideally also not duplicating with `--help`. The existing duplication of the config file and the hacking page is already an issue because they constantly get out of sync. I think we should work on something that generates everything from one single source file, maybe in parsable a format like YAML.

GiteaMirror commented

2025-11-02 06:23:20 -06:00

@bagasme commented on GitHub (May 26, 2020):

@silverwind file formats and conventions is also common on manpages (as man 5 /etc/sudoers or similar).

nevertheless, I like your idea of generate docs from single files. What about your suggestion?

@bagasme commented on GitHub (May 26, 2020): @silverwind file formats and conventions is also common on manpages (as `man 5 /etc/sudoers` or similar). nevertheless, I like your idea of generate docs from single files. What about your suggestion?

GiteaMirror commented

2025-11-02 06:23:20 -06:00

@silverwind commented on GitHub (May 26, 2020):

For config, I could see

configOptions:
  - name: APP_NAME
    default: "Gitea: Git with a cup of tea"
    comment: App name that shows in every page title
  - name: RUN_USER
    default: git
    comment: Change it if you run locally
  - name: RUN_MODE
    default: dev
    comment: Either "dev", "prod" or "test", default is "dev"
  - name: repository.ROOT
    default: ""
    comment: ""
  - name: repository.SCRIPT_TYPE
    default: bash
    comment: ""
  - name: repository.ANSI_CHARSET
    default: ""
    comment: Default ANSI charset

This format should be easy to parse in a script (I'd say either Go, JS or even Python) and it can generate both app.ini.sample and the hacking doc. A similar format could be used for --help and the manpage if you add a key like cliArguments with a similar format.

@silverwind commented on GitHub (May 26, 2020): For config, I could see ```yaml configOptions: - name: APP_NAME default: "Gitea: Git with a cup of tea" comment: App name that shows in every page title - name: RUN_USER default: git comment: Change it if you run locally - name: RUN_MODE default: dev comment: Either "dev", "prod" or "test", default is "dev" - name: repository.ROOT default: "" comment: "" - name: repository.SCRIPT_TYPE default: bash comment: "" - name: repository.ANSI_CHARSET default: "" comment: Default ANSI charset ``` This format should be easy to parse in a script (I'd say either Go, JS or even Python) and it can generate both `app.ini.sample` and the hacking doc. A similar format could be used for `--help` and the manpage if you add a key like `cliArguments` with a similar format.

GiteaMirror commented

2025-11-02 06:23:20 -06:00

@zeripath commented on GitHub (May 26, 2020):

Generally I'd say keeping that this next to the code would be better.

Go generally suggests generating other formats from go not generating go from other formats.

In any case Go generate can quite easily reflect on structs to get their tags and if necessary can parse go files and their comments too.

@zeripath commented on GitHub (May 26, 2020): Generally I'd say keeping that this next to the code would be better. Go generally suggests generating other formats from go not generating go from other formats. In any case Go generate can quite easily reflect on structs to get their tags and if necessary can parse go files and their comments too.

GiteaMirror commented

2025-11-02 06:23:21 -06:00

@stale[bot] commented on GitHub (Jul 25, 2020):

This issue has been automatically marked as stale because it has not had recent activity. I am here to help clear issues left open even if solved or waiting for more insight. This issue will be closed if no further activity occurs during the next 2 weeks. If the issue is still valid just add a comment to keep it alive. Thank you for your contributions.

@stale[bot] commented on GitHub (Jul 25, 2020): This issue has been automatically marked as stale because it has not had recent activity. I am here to help clear issues left open even if solved or waiting for more insight. This issue will be closed if no further activity occurs during the next 2 weeks. If the issue is still valid just add a comment to keep it alive. Thank you for your contributions.

GiteaMirror commented

2025-11-02 06:23:21 -06:00

@6543 commented on GitHub (Nov 5, 2020):

I think #13429 will close this partially