search

universal-ctags / ctags

A maintained ctags implementation
https://ctags.io
GNU General Public License v2.0
6.49k stars 620 forks source link

Docs: get rid of the optlib man page and just point to docs.ctags.io #1835

Open hadrielk opened 6 years ago

hadrielk commented 6 years ago

I was updating the man page for optlib (man/ctags-optlib.7.rst.in), and it feels very redundant with the optlib "Extending ctags" chapter of http://docs.ctags.io, mostly from docs/optlib.rst.

So I'm wondering: why do we need to document this stuff twice? Why don't we just have the main man page say to go read http://docs.ctags.io/en/latest/extending.html for details about extending ctags? We can still list the non-experimental optlib options in the main man page, as they mostly already are, but just say to go read http://docs.ctags.io/en/latest/extending.html for details.

I don't think people will be annoyed at having to go online to read about extending ctags - it's not simple/basic usage, really.

Even the current main man page feels too big and too detailed, in my opinion. I mean this isn't the 1980's. People have internet access. The man page should give the basics, but details could be left for online docs. For example, the section on "Guessing parser", "OPERATIONAL DETAILS", "How to use with ", and perhaps even "TAG FILE FORMAT" - those can go online only. But that's just my opinion, and perhaps too radical.(?)

masatake commented 6 years ago

I will make an answer for this. Please, wait for a while.

masatake commented 6 years ago

Sorry to be late.

We maintain two documents for 3 reasons.

  1. My English skill. I would like to advertise a new feature I added. On the other hand, I would like to make our documents readable. So, I put documents not reviewed yet on the website. Reviewed documents are moved to the man pages incrementally. When I move documents to the man pages from the website, I put marker "IN MAN PAGE" on the documents at the website. The sections with the makers should be removed from the website. I planed removing in the future by myself. However, of course, you can do it.

  2. Staging new features. I am a bad maintainer; I like to add random new features. I put the documentation for a new feature first. After getting feedback and getting experiences about the new feature, I can decide whether we should support the feature in the released version. I will write about features that I think we should support in the released version in the man pages. The man pages describe stable features. The web pages describe unstable features.

  3. Different audiences. The web pages are for ctags developers. The man pages are for ctags users.

I have wanted to put the man pages on our website(https://ctags.io) (##1444). But I think we should bundle well-explained man pages to the source tarball.

Splitting the big man page into smaller ones are o.k. I'm thinking about introducing tags(5) man page which explains the file format.

masatake commented 4 years ago

Thanks to @k-takata, the man pages are online. Reordering the sections in ctags(1) is in progress.