Re: Why does Nmap not install .luadoc files?

[Fyodor <fyodor () nmap org>]

On Mon, Dec 2, 2013 at 7:46 PM, Daniel Miller <bonsaiviking () gmail com>wrote:

> List,
>
> Is there any reason that the .luadoc files (placeholder and
> documentation for compiled-C NSE libraries) are not installed as part
> of "make install"? I understand there could be some small disk savings
> (68 KB at last count), but I think that having full documentation with
> the installation makes more sense. In fact, doesn't Zenmap parse these
> files for its script-args help text?

Warning: This is one of those emails where I start arguing against
something and then sort of change my mind midstream...

We are usually pretty strict about what documentation we provide/install in
the packages.  Each piece may seem small, but added together they can
really bloat the Nmap install size.  For example, we include the Nmap man
page (nroff) on Unix installs because it is an extremely common
documentation format.  But we don't include it on Windows where man pages
are rarely used.  We don't even include the HTML-rendered man page on
Windows because it seems much more likely that people will grab it online.
 We don't include the translated man pages in the binary packages either
(though we do in the tarball).

However, we have many megabytes of rendered documentation in numerous
languages on the web site, and I think it's better to direct users there
rather than either substantially bloat the packages with all that or
install a small and incomplete subset on their machine.

It's true that documentation on the system would exactly correspond to the
version of Nmap they have installed while the nmap.org documentation is for
the latest Nmap version.  While the former does have advantages, so does
the latter.  By reading the latest version of the docs, they may find a
feature which doesn't exist on their old Nmap and upgade to take advantage
of it.  And they can avoid doing things like writing a script to an old API
which wouldn't work with newer Nmap.

But on the other hand, we effectively include the luadoc for all the other
libraries and scripts because they are integrated with the code.  And we
already include the .luadoc in the Nmap source tarball too.  And given how
small these 6 files are compared to the rest of it, maybe it does make
sense to include them.  Looking at our current packages it seems the status
is:

Nmap Windows Self-Installer: luadoc are included and installed
Nmap Source Tarball: luadoc included but not installed
Nmap binary/src RPMs: luadoc not included or installed
Nmap Mac Installer: I'm not sure

I think we should be consistent (either always install/include or never),
and the arguments for installing the .luadoc are reasonable.  So I think
adding them to the make install target and the RPMs would be great.  And
maybe someone with a mac can report whether they have nmap.luadoc in their
nselib directory?

Cheers,
Fyodor
_______________________________________________
Sent through the dev mailing list
http://nmap.org/mailman/listinfo/dev
Archived at http://seclists.org/nmap-dev/