Online documentation and version differences

Online documentation and version differences

[Mike Mason]

Currently, the online documentation (man pages, language reference) reflects the current SystemTap source (at least that's the goal).  However, the various distros have different SystemTap functionality, depending on what snapshot they used.  The core is the same, but some details are different.  When we send users to the online documentation, it sometimes does not reflect the version they're using.

What, if anything, should we do about this?  We can certainly refer them to they're installed man pages as opposed to the online version, but there is only one version of the language reference.  It would be next to impossible to track features by distro version in the online reference.  However, if we packaged the reference in the SystemTap rpm, it would theoretically match the features at the time the snapshot was taken.  We could then tell users to refer to the language reference installed on their system instead of the online version.

Thoughts?

Mike

Re: Online documentation and version differences

[Mike Mason]

One week ago I posted this concern regarding the accuracy of the language reference and have received no responses so far.  Did it not make it to the list?  I'd like others opinions on how to keep the language reference accurate for multiple versions.

Mike

Mike Mason wrote:
> Currently, the online documentation (man pages, language reference) 
> reflects the current SystemTap source (at least that's the goal).  
> However, the various distros have different SystemTap functionality, 
> depending on what snapshot they used.  The core is the same, but some 
> details are different.  When we send users to the online documentation, 
> it sometimes does not reflect the version they're using.
> 
> What, if anything, should we do about this?  We can certainly refer them 
> to they're installed man pages as opposed to the online version, but 
> there is only one version of the language reference.  It would be next 
> to impossible to track features by distro version in the online 
> reference.  However, if we packaged the reference in the SystemTap rpm, 
> it would theoretically match the features at the time the snapshot was 
> taken.  We could then tell users to refer to the language reference 
> installed on their system instead of the online version.
> 
> Thoughts?
> 
> Mike

Re: Online documentation and version differences

[Stone, Joshua I]

Mike Mason wrote:
> One week ago I posted this concern regarding the accuracy of the language 
> reference and have received no responses so far.  Did it not make it to the 
> list?  I'd like others opinions on how to keep the language reference 
> accurate for multiple versions.

It does sound reasonable to package the reference into the RPM, just as
we do for the man pages.  Something like /usr/share/systemtap/doc/ would
be fine.

For online docs, we could keep an archive for released versions as many
other projects do.  We may need to get more formal about what a released
version means though...

Josh

Re: Online documentation and version differences

[Frank Ch. Eigler]

Hi -

I am open to moving e.g.  the tutorial and/or the language reference
paper into the install tree.  A prerequisite would be to move them
from doc/ to under src/doc/ in the repository.  Ideally, the build
process should format them, which in turn means having tex etc. as
buildprereq's in the RPM.

- FChE

Re: Online documentation and version differences

[Frank Ch. Eigler]

I wrote:

> I am open to moving e.g.  the tutorial and/or the language reference
> paper into the install tree.  A prerequisite would be to move them
> from doc/ to under src/doc/ in the repository.  Ideally, the build
> process should format them, which in turn means having tex etc. as
> buildprereq's in the RPM.

This is now done: $builddir/doc/{tutorial,langref}.pdf are now
present.  Please let me know if the build system modifications break
something for you.

- FChE

Re: Online documentation and version differences

[Masami Hiramatsu]

Frank Ch. Eigler wrote:
> This is now done: $builddir/doc/{tutorial,langref}.pdf are now
> present.  Please let me know if the build system modifications break
> something for you.

Hi Frank,
On rhel5.1, I failed to build rpm package(tutorial.tex) because nomencl.sty
included in tetex-latex-3.0-33.2.el5_1.2 was old and did not support "compatible"
option.

Thanks,

-- 
Masami Hiramatsu

Software Engineer
Hitachi Computer Products (America) Inc.
Software Solutions Division

e-mail: mhiramat@redhat.com