Writing Manpage

[bagasme]

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:

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

[techknowlogick]

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

[lafriks]

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

[bagasme]

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

[techknowlogick]

Not in manual, but here is a code reference: https://github.com/urfave/cli/blob/841e5b03ad972b9578bb8ad73441e9d9a51d3c14/docs.go#L24

[silverwind]

I see that #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.

[bagasme]

@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?

[silverwind]

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.

[zeripath]

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.

[stale]

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.

[6543]

I think #13429 will close this partially

• the Config Cheat Sheet still need a solution ...