shiro-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Brian Demers <brian.dem...@gmail.com>
Subject Re: Versioned Reference Manual
Date Tue, 24 May 2011 15:54:10 GMT
I tried to update the doc this weekend and it took me a while to figure out
how to do it.  The doc located at http://shiro.apache.org/ or readme
https://svn.apache.org/repos/asf/shiro/site-template/README,  do not mention
the confluence site located at:
https://cwiki.apache.org/confluence/display/SHIRO/

Google found it of course, but then I needed to create a new login.

What I am getting at is I think the current site doc is a bit complicated to
update.  I like the look of the Shiro site better then a confluence page,
but it does not have the wiki feel to it.

If we say with the current export functionality, maybe we should add an edit
button that would navigate back to cwiki ? Or a page that describes the
process on the Shrio site?

Any thoughts?





On Thu, May 19, 2011 at 1:49 PM, Tauren Mills <tauren@groovee.com> wrote:

> Les,
>
> A while back I was thinking about ways to elegantly display versioned
> information and had some UI ideas. My solution was to keep everything on
> the
> same page, but use client-side Javascript to dynamically show and hide
> different versions. This wouldn't be at all hard to do, but I haven't
> actually implemented it yet. I'll share the basic concept here -- perhaps
> you might find it worthwhile.
>
> Take http://shiro.apache.org/web.html as an example and imagine docs are
> marked up like this:
>
> <section>
>  <h1>Apache Shiro Web Configuration</h1>
>  <p>...</p>
>  <h2>Default Configuration</h2>
>  <p class="ge1_2">In Shiro 1.2 and later, standard web applications...</p>
>  <p class="le1_1">The simplest way to enable Shiro...</p>
>  <div class="ge1_2">
>    <h3>Custom WebEnvironment</h3>
>    <p>By default the EnvironmentLoaderListener...</p>
>  </div>
>  <div class="eq1_1 eq1_0">
>    <h3>Custom Path</h3>
>    <p>If you do not want to place..</p>
>  </div>
> </section>
>
> At the top of a page (and maybe even next to each block) would be a
> javascript widget that allows users to select the documentation version
> they
> would like to view. Each version number would appear in a toggle button, so
> that multiple version could be viewed at the same time. The [Latest] button
> would be selected by default:
>
> [Latest] [1.3] [1.2] [1.1] [1.0] [All]
>
> Javascript code would determine which classes should be hidden and which
> should be shown. The class names would represent a specific version (eq), a
> version and older (le), or a version and newer (ge). So if [1.3] is
> selected, classes eq1_3, ge1_2, ge1_1 would be shown and eq1_1, le1_2 would
> be hidden.
>
> In addition, CSS would be used based on the class names to add a version
> number in the page margin next to each paragraph, section, callout, title,
> or whatever. I'm imagining this as a list of small version numbers in a
> light grey text to either the left or right of each "block" on the page.
>
> Content without a versioning class would be shown at all times.
>
> This would allow you to write the documentation all on a single page, but
> only show what matters for a particular version. It also makes sure to
> reenforce the version number that a specific block of content pertains to
> all through the page. If multiple versions are being viewed at the same
> time, the older versions could be slightly dulled with the text in a
> lighter
>  grey so that it is obvious what is new and what is old.
>
> Just some ideas. I'd be happy to write the javascript widget if you decide
> to go this route.
>
> Tauren
>
>
> On Thu, May 19, 2011 at 7:30 AM, Les Hazlewood <lhazlewood@apache.org
> >wrote:
>
> > On Wed, May 18, 2011 at 3:26 PM, Kalle Korhonen
> > <kalle.o.korhonen@gmail.com> wrote:
> > > I'd say the most practical and most cost-effective
> > > solution is to write the user guides etc. in such a way that they are
> > > as version agnostic as possible and then refer to the Javadocs when
> > > things differ.
> >
> > This also doesn't work out well in my experience - there is no way to
> > easily do this if you're adding a new feature or using an alternative
> > to an existing one.  The example here is the web documentation I just
> > added - in 1.2, it is done one way, in 1.1 a different way.
> >
> > I may be being dense here, but I can't see how to represent that
> > information easily in the same page without introducing inelegant
> > documentation chunks based on version.  I'd love to hear suggestions
> > on how to improve this for example.
> >
> > Best,
> >
> > Les
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message