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

%WHATDOESITAFFECT%
edit

Implementation

Tasks.Item11437

-- 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
1.1.5
Main API.
1.1.5
Parameter passing for custom macros
1.1.5
URL parameters
1.1.5
Calls to external commands; untainting
1.1.5
Metadata for webs or topics. ALERT! 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.
1.1.5
Exception used raise an access control violation.
1.1.5
Exception used to raise a request to output a preformatted page.
1.1.5
 
1.2.0
 
1.2.0
 
1.2.0
 
1.1.5
Just to access $SESSION and $VERSION
1.1.5
Time handling functions.
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
??
Anyone implementing a custom login manager needs to implement the methods documented in this module.
??
Same for custom Password managers.
??
And Mapping managers.
??
Custom loggers

-- GeorgeClark - 17 Mar 2012

George, I integrated your updates.

Used For Package First Published Comment LocalSite.cfg Setting
Plugins/Contribs
1.1.5
Main API.
N/A
Plugins/Contribs
1.1.5
Parameter passing for custom macros
N/A
Plugins/Contribs
1.1.5
URL parameters
N/A
Plugins/Contribs
1.1.5
Calls to external commands; untainting
N/A
Plugins/Contribs
1.1.5
Metadata for webs or topics. ALERT! 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
1.1.5
Exception used raise an access control violation.
N/A
Plugins/Contribs
1.1.5
Exception used to raise a request to output a preformatted page.
N/A
Plugins/Contribs
1.1.5
 
N/A
Plugins/Contribs
1.1.5
Just to access $SESSION and $VERSION
N/A
Plugins/Contribs
1.1.5
Time handling functions.
N/A
Integration
1.1.5
Custom Authentication.
$Foswiki::cfg{PasswordManager}
Integration
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
1.1.5
How users login (i.e. HTML forms or Apache)
$Foswiki::cfg{LoginManager}
Integration
1.1.5
Custom loggers.
$Foswiki::cfg{Log}{Implementation}

-- KipLubliner - 18 Mar 2012

Interface for Plugin, Contrib and Skin Developers

See DevelopingPlugins for more information.
Package First Published Comment
1.1.5
Main API.
1.1.5
Parameter passing for custom macros
1.1.5
URL parameters
1.1.5
Calls to external commands; untainting
1.1.5
Metadata for webs or topics. ALERT! 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.
1.1.5
Exception used raise an access control violation.
1.1.5
Exception used to raise a request to output a preformatted page.
1.1.5
 
1.1.5
Just to access $SESSION and $VERSION
1.1.5
Time handling functions.

Interface for Advanced Integration

See UserAuthentication for more information.
Package First Published Comment LocalSite.cfg Setting
1.1.5
Custom Authentication.
$Foswiki::cfg{PasswordManager}
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}
1.1.5
How users login (i.e. HTML forms or Apache)
$Foswiki::cfg{LoginManager}
1.1.5
Custom loggers.
$Foswiki::cfg{Log}{Implementation}

-- KipLubliner - 20 Mar 2012
Topic attachments
I Attachment Action Size Date Who Comment
PerlDoc.txttxt PerlDoc.txt manage 1 K 13 Jan 2012 - 01:57 KipLubliner  
PublishedAPI.txttxt PublishedAPI.txt manage 1 K 13 Jan 2012 - 01:46 KipLubliner  
Screen_shot_2012-01-08_at_3.24.39_PM.pngpng Screen_shot_2012-01-08_at_3.24.39_PM.png manage 59 K 08 Jan 2012 - 21:11 KipLubliner package navigation
doc.pmpm doc.pm manage 8 K 13 Jan 2012 - 01:45 KipLubliner  
packages2.pngpng packages2.png manage 537 K 12 Jan 2012 - 03:04 KipLubliner  
Topic revision: r30 - 20 Mar 2012, KipLubliner - This page was cached on 08 Sep 2020 - 06:54.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy