Summary: | ASTERISK-15358: [patch] Asterisk man page outdated | ||
Reporter: | Tzafrir Cohen (tzafrir) | Labels: | |
Date Opened: | 2009-12-23 02:01:59.000-0600 | Date Closed: | 2012-02-15 08:42:22.000-0600 |
Priority: | Minor | Regression? | No |
Status: | Closed/Complete | Components: | 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 |