[openib-general] Re: documentation under src dir

[Hal Rosenstock]

On Wed, 2005-07-06 at 18:08, Michael S. Tsirkin wrote:
> Quoting r. Hal Rosenstock <halr at voltaire.com>:
> > Subject: Re: documentation under src dir
> > 
> > On Tue, 2005-07-05 at 03:24, Michael S. Tsirkin wrote:
> > > Hal, Shahar, could you please move the following files
> > > outside the src directory?
> > > 
> > > ./trunk/src/userspace/management/osm/doc/OpenSM_RN.pdf
> > > ./trunk/src/userspace/management/osm/doc/OpenSM_UM.pdf
> > > 
> > > These are not sources, so they dont belong in src.
> > > I suggest removing OpenSM_RN.pdf and moving OpenSM_UM.pdf to the docs
> > > section on the web site.
> > 
> > Other userspace tarballs include the documentation under a doc
> > subdirectory.
> 
> pdf? I think its uncommon. where?

It may be uncommon but it is done.
One example is subversion:
subversion-1.1.0/doc/book/book/svn-book.pdf

> It seems to me that source tarballs usually dont include docs in noneditable
> format. In my opinion, documentation that isnt in plain text, sgml, or
> something like that doesnt belong in src (pdfs can be compiled on demand).
> 
> > Guess the inconsistency here is that it is under 
> > src/userspace/(management/osm).
> > I'm not sure what the best way to handle
> > this is.
> 
> I think OpenSM_RN.pdf should go since its just release notes
> for 1.6.1 opensm from gold cd.

It (1.6.1) is also the basis for the current version of the OpenIB
OpenSM and so is pertinent here. There have been some bug fixes and
incorporation of functions beyond this (but I'm not sure they affect the
list in the release notes).

> OpenSM_UM.pdf should ideally converted to text or sgml or something
> like this so we can generate standard man/info pages.
> Short term, I'd advocate moving it to the web.

Ideally both of these would be converted and made into OpenIB documents.
I don't have the sources nor have I had the time to chase this down.

> > One option is as you suggest: move these elsewhere; a second to
> > leave this alone; and a third to restructure the naming of the tree so
> > this is not a problem.
> > If they are to be moved elsewhere, would we
> > create a doc/userspace/... ?
> 
> Any way that doesnt force me to pull binaries on each
> checkout works for me.

-- Hal