[Home]

Summary:ASTERISK-15358: [patch] Asterisk man page outdated
Reporter:Tzafrir Cohen (tzafrir)Labels:
Date Opened:2009-12-23 02:01:59.000-0600Date Closed:2012-02-15 08:42:22.000-0600
Priority:MinorRegression?No
Status:Closed/CompleteComponents:Documentation
Versions:Frequency of
Occurrence
Related
Issues:
Environment:Attachments:( 0) 20091228__issue16505__3.diff.txt
( 1) asterisk_sgml_fixes_demo.diff
( 2) manpages.diff
( 3) new_asterisk.8
Description:The man page included with Asterisk is outdated. Does not include a number of options.

There is also doc/asterisk.sgml . It has been updated once or twice in the past. I don't see any Makefile target to generate a man page from it.

Furthermore, to reference a recent Debian bug: the man page is supposed to also be used as a man page for rasterisk, but does not mention it.

Likewise undocumented is the ASTERISK_PROMPT variable.
Comments:By: Leif Madsen (lmadsen) 2010-03-02 13:53:15.000-0600

Curious if the reporter or anyone else is interested in testing this? How easily does this slip out of date and would require to be updated?

By: Andrew Latham (lathama) 2011-02-06 20:23:33.000-0600

I will add this to my documentation updates.

By: Andrew Latham (lathama) 2011-02-07 06:08:25.000-0600

This is fun, all the man pages say "Asterisk 1.6".  Will start separating the pages.

By: Digium Subversion (svnbot) 2011-02-07 19:45:05.000-0600

Repository: asterisk
Revision: 306826

U   branches/1.8/UPGRADE.txt
U   branches/1.8/doc/asterisk.sgml
U   branches/1.8/include/asterisk/doxygen/mantisworkflow.h
U   branches/1.8/include/asterisk/manager.h

------------------------------------------------------------------------
r306826 | lathama | 2011-02-07 19:45:04 -0600 (Mon, 07 Feb 2011) | 9 lines

Documentation Updates.

More updates to the removed doc folder and
start updates to the man page.

(issue ASTERISK-15358)
Reported by: tzafrir
Tested by: lathama

------------------------------------------------------------------------

http://svn.digium.com/view/asterisk?view=rev&revision=306826

By: Digium Subversion (svnbot) 2011-02-07 20:05:04.000-0600

Repository: asterisk
Revision: 306827

U   trunk/doc/asterisk.sgml

------------------------------------------------------------------------
r306827 | lathama | 2011-02-07 20:05:03 -0600 (Mon, 07 Feb 2011) | 8 lines

Documentation Updates.

Start updates to the man pages.

(issue ASTERISK-15358)
Reported by: tzafrir
Tested by: lathama

------------------------------------------------------------------------

http://svn.digium.com/view/asterisk?view=rev&revision=306827

By: Leif Madsen (lmadsen) 2011-02-07 22:30:34.000-0600

Honestly, all documentation should probably be shifted to the wiki. I'm not in favour of having the same documentation in multiple locations, especially when those locations are not easy to update.

By: Tzafrir Cohen (tzafrir) 2011-02-08 02:07:56.000-0600

Can you generate a man page from the wiki?

By: Tzafrir Cohen (tzafrir) 2011-02-08 02:18:56.000-0600

lathama: note that you updated asterisk.sgml, but not the actual man page ('make -C doc'). Update it?

By: Tzafrir Cohen (tzafrir) 2011-02-08 03:47:40.000-0600

Uploaded some initial updates to asterisk.sgml. Not complete yet but this shows what I'm shooting for.

By: Andrew Latham (lathama) 2011-02-08 05:29:17.000-0600

Leif, this is a process that is just starting and Tzafrir is right that this content is both out of date and hard to manage.

Tzafrir, I will work on this today.  I will need help with testing this with different versions of man.  I assume we need to test on Apple MacOSX in addition to all the Linux, *BSD, Solaris platforms.

By: Andrew Latham (lathama) 2011-02-08 07:27:23.000-0600

Tzafrir, I notice that you mention some undocumented settings in asterisk.conf.  I will add those today.

By: Digium Subversion (svnbot) 2011-02-08 14:22:36.000-0600

Repository: asterisk
Revision: 306999

U   branches/1.8/configs/asterisk.conf.sample
U   branches/1.8/configs/voicemail.conf.sample
U   branches/1.8/doc/asterisk.8
U   branches/1.8/doc/asterisk.sgml

------------------------------------------------------------------------
r306999 | lathama | 2011-02-08 14:22:36 -0600 (Tue, 08 Feb 2011) | 12 lines

Documentation Updates

Note default polling setting in voicemail.conf
Add missing config to asterisk.conf
Update manpage

(issue ASTERISK-15358)
Reported by: tzafrir
Patches:
     asterisk_sgml_fixes_demo.diff uploaded by tzafrir (license 46)
Tested by: lathama, tzafrir

------------------------------------------------------------------------

http://svn.digium.com/view/asterisk?view=rev&revision=306999

By: Digium Subversion (svnbot) 2011-02-08 14:31:14.000-0600

Repository: asterisk
Revision: 307041

_U  trunk/
U   trunk/configs/asterisk.conf.sample
U   trunk/configs/voicemail.conf.sample
U   trunk/doc/asterisk.8
U   trunk/doc/asterisk.sgml

------------------------------------------------------------------------
r307041 | lathama | 2011-02-08 14:31:13 -0600 (Tue, 08 Feb 2011) | 13 lines

Documentation Updates

Note default polling setting in voicemail.conf
Add missing config to asterisk.conf
Update manpage

(issue ASTERISK-15358)
Reported by: tzafrir
Patches:
    asterisk_sgml_fixes_demo.diff uploaded by tzafrir (license 46)
Tested by: lathama, tzafrir


------------------------------------------------------------------------

http://svn.digium.com/view/asterisk?view=rev&revision=307041

By: Andrew Latham (lathama) 2011-02-10 06:34:21.000-0600

I have a final version of the man page I am ready to upload for 1.6.2, 1.8, Trunk.  After looking and Chatting with Tzafrir (He created some and manages the man pages for all the DAHDI tools) I learned that the sgml and other methods of exporting to man pages still work but have very poor or outdated support. I need to duplicate and change for rasterisk also.  I will update what I have to this task and get some peer review first.

By: Andrew Latham (lathama) 2011-02-10 06:54:30.000-0600

Edited with gmanedit and tested with man -l <man file name>

* Note: KATE also supports roff markup

txt2man, docbook-to-man, xmltoman and other programs were tested but all are outdated solutions.  Editing the roff directly seams like the best idea.  I will delete or switch the asterisk.sgml when ready to close this ticket.

By: Leif Madsen (lmadsen) 2011-02-10 12:24:55.000-0600

Right, but what I'm saying is why bother updating the manpages at all when all documentation should be shifted to the wiki, instead of having the same documentation in two locations?

By: Andrew Latham (lathama) 2011-02-10 12:33:10.000-0600

Because some distros, like Debian require a manpage for every program.

By: Andrew Latham (lathama) 2011-02-23 07:41:47.000-0600

Uploaded a more complete diff.  The sgml and Makefile can be removed. If people want to keep the sgml and Makefile they should delete the man page.  It is silly to have both.  I also started updating the manpages in /contrib/scripts/  the documentation on the IAX RSA is missing from the wiki but exists on voip-info.

By: Andrew Latham (lathama) 2011-06-21 12:02:51.013-0500

Can this be looked at for 1.10 or do I need to do the review board for this?

By: Andrew Latham (lathama) 2012-02-15 08:42:22.400-0600

Lack of interest