Are the 'How to' documents present as man pages?

Are the 'How to' documents present as man pages?

[Kaartic Sivaraam]

I was reading the 'git revert' documentation and found the following
line in it,


    -m parent-number
    --mainline parent-number

        ...

        See the revert-a-faulty-merge How-To[1] for more details.


It says that the 'How-To' is present in the first section of the man
page. I tried to access it to get this,


    $ man 1 revert-a-faulty-merge How-To
    No manual entry for revert-a-faulty-merge in section 1
    No manual entry for How-To in section 1


That made me wonder whether the 'How-To' documents were present as man
pages and were installed when git is installed.

In case they are, how should I be accessing them? In case they aren't
doesn't the above seem misleading?


    -- 
    Kaartic

Re: Are the 'How to' documents present as man pages?

[Simon Ruderich]

On Sat, Sep 16, 2017 at 10:30:43AM +0530, Kaartic Sivaraam wrote:
> I was reading the 'git revert' documentation and found the following
> line in it,
>
>     -m parent-number
>     --mainline parent-number
>
>         ...
>
>         See the revert-a-faulty-merge How-To[1] for more details.

Square brackets indicate links, you should have a NOTES section
at the bottom of the man page which contains something like this:

        1. revert-a-faulty-merge How-To
           file:///usr/share/doc/git/html/howto/revert-a-faulty-merge.html

To my knowledge those are not available as man pages.

> It says that the 'How-To' is present in the first section of the man
> page. I tried to access it to get this,

References to other man pages generally use round brackets, for
example git-merge(1).

I checked the git-scm.com website [1] and interestingly they use
square brackets for these references which confused me a little.
Not sure if it's worth changing though.

Regards
Simon

[1]: https://git-scm.com/docs/git-revert
-- 
+ privacy is necessary
+ using gnupg http://gnupg.org
+ public key id: 0x92FEFDB7E44C32F9

Re: Are the 'How to' documents present as man pages?

[Kaartic Sivaraam]

On Sat, 2017-09-16 at 10:54 +0200, Simon Ruderich wrote:
> On Sat, Sep 16, 2017 at 10:30:43AM +0530, Kaartic Sivaraam wrote:
> > I was reading the 'git revert' documentation and found the following
> > line in it,
> > 
> >     -m parent-number
> >     --mainline parent-number
> > 
> >         ...
> > 
> >         See the revert-a-faulty-merge How-To[1] for more details.
> 
> Square brackets indicate links, you should have a NOTES section
> at the bottom of the man page which contains something like this:
> 

Yes there is, thanks!

> References to other man pages generally use round brackets, for
> example git-merge(1).
> 

I didn't know they had different meanings for different brackets in man
pages. The asciidoc source itself uses square-brackets to refer to man
page sections. May the link to notes should be something like [note 1].
Not sure if it's possible to do that.

---
Kaartic

Re: Are the 'How to' documents present as man pages?

[Simon Ruderich]

On Sat, Sep 16, 2017 at 05:17:35PM +0530, Kaartic Sivaraam wrote:
>> References to other man pages generally use round brackets, for
>> example git-merge(1).
>
> I didn't know they had different meanings for different brackets in man
> pages. [snip]

Man pages in general use only round brackets to refer to another
man page with the given section (like stat(1) or stat(2)).

Square brackets have no special meaning, but are useful for
references like URLs.

Regards
Simon
-- 
+ privacy is necessary
+ using gnupg http://gnupg.org
+ public key id: 0x92FEFDB7E44C32F9