Feature Proposal: Add package navigation to Perl Doc

Motivation

Make it easier to access documentation.

Description and Documentation

Make it possible to browse through all the Perl Doc pages by package hierarchy:

• Links to "children" packages, with a brief summary of each child package
• Show "parent" packages by creating a new title on top of PerlDoc that has links to each "prefix" package
• The above is accomplished via %DOC_TITLE% and %DOC_CHILDREN% injected into PerlDoc in the same way as %SMELLS%.

Generate the summary of each child package by using the first few lines under ---++ package XXX in the pod. Find the first line that contains only whitespace, and truncate from there onwards.

Create a new topic called System.PublishedAPI that defines the API intended for end-users:

• Add a checkbox labelled "Public" to PerlDoc that determines if all sub-packages are shown, or only published ones.
• If the currently displayed package is in System.PublishedAPI, prefix it with "public" else with "internal".

Other odds and ends:

• If the public checkbox is clicked then methods that start with _ are suppressed.
• If PerlDoc is viewed with no package selected, render "Foswiki" by default.

See also a big picture of what packages currently link to each other (seeded with published packages).

Examples

This is currently checked into trunk and can be seen at http://trunk.foswiki.org/System/PerlDoc (much apologies for checking in code for a non AcceptedProposal, I had a misunderstanding).

The same code can be seen on my website: http://kiplubliner.com/view/System/PerlDoc

Impact

Implementation

Tasks.Item11437

• doc.pm
• PerlDoc.txt
• PublishedAPI.txt

-- Contributors: KipLubliner - 08 Jan 2012

Discussion

(Cleaned up description & comments; previous content can be seen at r16)

Open Issues:

• Some of the package descriptions don't look very good. E.g. the descriptions for Foswiki::*Iterator packages all simply tell us their parent class. But this information is available anyway (there already is code checked into trunk for scanning @ISA). I would be glad to help to clean up package descriptions, but I don't want to interfere with other development.
• Child packages are hidden behind a twisty. For a package like Foswiki with many children packages, this means that this is basically a 'modal' interface - the user has to decide to browse the class (Twisty is closed), or navigate the hierarchy (Twisty is open). I think that it would be nicer to use a "sidebar" to render the children (somewhat like javadoc).
• Should $VERSION and $RELEASE be rendered in package description? This seems specific only to Plugins / Contribs and the info is available elsewhere anyway.
• Per comment from CrawfordCurrie, Meta is going to change after release of Store2. Is it desirable to document that an API is going to become deprecated but is not currently?

This picture is going to change again soon. The ongoing work on Store2 is going to remove Meta in its current form. I've been reluctant to "publish" Form because the API is a bit s**t and needs work before being cast in stone (not least to allow other implementations of Form to exist). Prefs should only be access through Func. UI classes should not be published, nor should the cache. I removed Extensions from your list.

-- CrawfordCurrie - 12 Jan 2012

-- KipLubliner - 14 Jan 2012

Note that the bug item should be included in the "BugTracking" field of this topic for reference.

You broke the unit tests. I will fix them.

-- CrawfordCurrie - 15 Jan 2012

Thanks for your help! I have yet to learn how to run the unit tests locally. Also, I checked in a fix to your fix (so that viewing PerlDoc? without any parameters will display Foswiki package, and not ::).

-- KipLubliner - 15 Jan 2012

The "public only" checkbox does not work on 1.1.5 beta 1 because this topic does not exist: http://foswiki.org/System/PublishedAPI

This is the version of the file in trunk: http://trunk.foswiki.org/System/PublishedAPI

-- KipLubliner - 08 Mar 2012

GeorgeClark helped me update the manifest file for 1.1.5.

-- KipLubliner - 08 Mar 2012

Packages that should be in PublishedAPI. If any should be removed, please add a comment:

	package	Published?	Why / Why not?
package	Foswiki	No	But there are some things that need to be exposed, like expandStandardEscapes(), urlEncode(), etc. Also this is used by registered tag handlers. No there aren't - anything useful is exported through Foswiki::Func. This should definitely not be exported, and I would love to withdraw the export to registered tag handlers etc
package	Foswiki::Access	No	Foswiki::Func::checkAccessPermission()
package	Foswiki::AccessControlException	1.1.5
package	Foswiki::AggregateIterator	1.2.0
package	Foswiki::Attrs	1.1.5	used by registered tag handlers
package	Foswiki::Engine	No	Doesn't look like it needs to be exposed
package	Foswiki::Extensions	No	Whoops, non-existent package that I missed
package	Foswiki::Func	1.1.5	Duh
package	Foswiki::Iterator	1.1.5
package	Foswiki::LineIterator	1.2.0
package	Foswiki::ListIterator	1.2.0
package	Foswiki::LoginManager	No
package	Foswiki::LoginManager::ApacheLogin	No
package	Foswiki::LoginManager::TemplateLogin	No
package	Foswiki::Meta	1.1.5	Used by plugin handlers - but only a subset of the public methods (ie, be careful, things will change when needed)
package	Foswiki::OopsException	1.1.5
package	Foswiki::PageCache	No	I assume that methods will be added to Foswiki::Func, for adding dependencies etc??
package	Foswiki::Plugins	1.1.5	$SESSION, $VERSION - ie, its not a real API, just 2 global vars in that namespace. (which should really be deprecated and moved to be accessed via Func)
package	Foswiki::Prefs	No	Push/Pop context() are already exposed in Foswiki::Func
package	Foswiki::Query	No
package	Foswiki::Render	No	no exposed methods
package	Foswiki::Request	1.1.5	so plugin authors can get request params
package	Foswiki::Request::Upload	No
package	Foswiki::Response	No
package	Foswiki::Sandbox	1.1.5	"All calls to system functions, or handling of file names, should be brokered by the sysCommand function in this package." Also the taint routines should / need to be used from here.
package	Foswiki::Search::InfoCache	No
package	Foswiki::Time	1.1.5	Deprecated Foswiki::Func methods say to use this instead
package	Foswiki::UI	No
package	Foswiki::UI::Register	No
package	Foswiki::Users	No
package	Foswiki::Validation	1.2.0	The key validation methods here are useful to plugins - can we facade these via Func before 1.2.0 release?
package	Foswiki::WebFilter	No	no exposed methods

---

so 'released in' 1.2.0 means that we still have the opportunity to not release them and provide a narrower API via Foswiki::Func?

-- SvenDowideit - 14 Mar 2012

Updated version of PublishedAPI - for trunk. For 1.1 branch, I will remove references to packages that CC marked as 1.2.0.

Name	First Published	Comment
Foswiki::Func	1.1.5	Main API.
Foswiki::Attrs	1.1.5	Parameter passing for custom macros
Foswiki::Request	1.1.5	URL parameters
Foswiki::Sandbox	1.1.5	Calls to external commands; untainting
Foswiki::Meta	1.1.5	Metadata for webs or topics. This class may be changed after refactorings of the Foswiki internals, so please try to use Foswiki::Func instead if possible. Incompatible changes will only be made during a major release.
Foswiki::AccessControlException	1.1.5	Exception used raise an access control violation.
Foswiki::OopsException	1.1.5	Exception used to raise a request to output a preformatted page.
Foswiki::Iterator	1.1.5
Foswiki::AggregateIterator	1.2.0
Foswiki::LineIterator	1.2.0
Foswiki::ListIterator	1.2.0
Foswiki::Plugins	1.1.5	Just to access $SESSION and $VERSION
Foswiki::Time	1.1.5	Time handling functions.
Foswiki::Validation	1.2.0	The key validation methods here are useful to plugins - can we facade these via Func before 1.2.0 release?

-- KipLubliner - 17 Mar 2012

Hm. Aren't the following also "public" in that anyone implementing a custom Login or Mapping manager is required to override / implement their methods? My assumption would be that anything in confgure that is dynamically detected / presented as a choice, like the Password, Login and Mapping managers would need to be part of the public API. Probably the Logging manager as well, as we've wanted to encourage someone to write a more advanced logger.

Need footnotes however that these are not for use by Plugins, but are for the exclusive use of pluggable features.

Name	Public API	Comment
Foswiki::LoginManager	??	Anyone implementing a custom login manager needs to implement the methods documented in this module.
Foswiki::Users::Password	??	Same for custom Password managers.
Foswiki::UserMapping	??	And Mapping managers.
Foswiki::Logger	??	Custom loggers

-- GeorgeClark - 17 Mar 2012

George, I integrated your updates.

Used For	Package	First Published	Comment	LocalSite.cfg Setting
Plugins/Contribs	Foswiki::Func	1.1.5	Main API.	N/A
Plugins/Contribs	Foswiki::Attrs	1.1.5	Parameter passing for custom macros	N/A
Plugins/Contribs	Foswiki::Request	1.1.5	URL parameters	N/A
Plugins/Contribs	Foswiki::Sandbox	1.1.5	Calls to external commands; untainting	N/A
Plugins/Contribs	Foswiki::Meta	1.1.5	Metadata for webs or topics. This class may be changed after refactorings of the Foswiki internals, so please try to use Foswiki::Func instead if possible. Incompatible changes will only be made during a major release.	N/A
Plugins/Contribs	Foswiki::AccessControlException	1.1.5	Exception used raise an access control violation.	N/A
Plugins/Contribs	Foswiki::OopsException	1.1.5	Exception used to raise a request to output a preformatted page.	N/A
Plugins/Contribs	Foswiki::Iterator	1.1.5		N/A
Plugins/Contribs	Foswiki::Plugins	1.1.5	Just to access $SESSION and $VERSION	N/A
Plugins/Contribs	Foswiki::Time	1.1.5	Time handling functions.	N/A
Integration	Foswiki::Users::Password	1.1.5	Custom Authentication.	$Foswiki::cfg{PasswordManager}
Integration	Foswiki::UserMapping	1.1.5	User mapping is the process by which Foswiki maps from a username (a login name) to a display name and back. It is also where groups are maintained.	$Foswiki::cfg{UserMappingManager}
Integration	Foswiki::LoginManager	1.1.5	How users login (i.e. HTML forms or Apache)	$Foswiki::cfg{LoginManager}
Integration	Foswiki::Logger	1.1.5	Custom loggers.	$Foswiki::cfg{Log}{Implementation}

• See UserAuthentication for more information about Integration.
• See DevelopingPlugins for more information about Plugins and Contribs.

-- KipLubliner - 18 Mar 2012

Interface for Plugin, Contrib and Skin Developers

See DevelopingPlugins for more information.

Package	First Published	Comment
Foswiki::Func	1.1.5	Main API.
Foswiki::Attrs	1.1.5	Parameter passing for custom macros
Foswiki::Request	1.1.5	URL parameters
Foswiki::Sandbox	1.1.5	Calls to external commands; untainting
Foswiki::Meta	1.1.5	Metadata for webs or topics. This class may be changed after refactorings of the Foswiki internals, so please try to use Foswiki::Func instead if possible. Incompatible changes will only be made during a major release.
Foswiki::AccessControlException	1.1.5	Exception used raise an access control violation.
Foswiki::OopsException	1.1.5	Exception used to raise a request to output a preformatted page.
Foswiki::Iterator	1.1.5
Foswiki::Plugins	1.1.5	Just to access $SESSION and $VERSION
Foswiki::Time	1.1.5	Time handling functions.

Interface for Advanced Integration

See UserAuthentication for more information.

Package	First Published	Comment	LocalSite.cfg Setting
Foswiki::Users::Password	1.1.5	Custom Authentication.	$Foswiki::cfg{PasswordManager}
Foswiki::UserMapping	1.1.5	User mapping is the process by which Foswiki maps from a username (a login name) to a display name and back. It is also where groups are maintained.	$Foswiki::cfg{UserMappingManager}
Foswiki::LoginManager	1.1.5	How users login (i.e. HTML forms or Apache)	$Foswiki::cfg{LoginManager}
Foswiki::Logger	1.1.5	Custom loggers.	$Foswiki::cfg{Log}{Implementation}

-- KipLubliner - 20 Mar 2012