INSTALL: Grammar advice?

[Nathan Hartman <ha...@gmail.com>]

In INSTALL, there is this awkward use of (optionally):

        The Netwide Assembler (NASM) is used to build the (optionally)
        assembler modules of OpenSSL.

Which of these is the best fix?

(1)     The Netwide Assembler (NASM) is used to (optionally) build the
        assembler modules of OpenSSL.

(2)     The Netwide Assembler (NASM) is (optionally) used to build the
        assembler modules of OpenSSL.

(3)     The Netwide Assembler (NASM) is used to build the (optional)
        assembler modules of OpenSSL.

Thanks!
Nathan

Re: INSTALL: Grammar advice?

[Nathan Hartman <ha...@gmail.com>]

Argh, forgot to hit reply all again...

On Thu, Oct 31, 2019 at 11:23 AM Julian Foad <ju...@apache.org> wrote:

> To be blunt: these instructions need a lot more fixing than just grammar.
>

I would like to add, not all hope is lost. We have a far better INSTALL
than quite a few projects that I've ventured to build myself over the
years.

The very first time I tested Subversion for use at $work (circa 1.4), I
didn't download a package; I built from source by following INSTALL and
everything built and worked perfectly the very first time. That was my
first impression, it was a good one, and this is our version control
system to this day. :-)

Yes, INSTALL needs help. Help is on its way!

Re: INSTALL: Grammar advice?

[Nathan Hartman <ha...@gmail.com>]

On Thu, Oct 31, 2019 at 11:23 AM Julian Foad <ju...@apache.org> wrote:

> Nathan Hartman wrote:
> > In INSTALL, there is this awkward use of (optionally):
> >
> >          The Netwide Assembler (NASM) is used to build the (optionally)
> >          assembler modules of OpenSSL.
> >
> > Which of these is the best fix?
>
> To be blunt: these instructions need a lot more fixing than just grammar.
>

I noticed that; especially the section about building on Windows,
which I intend to basically rewrite simultaneously while setting up my
Windows build environment. I can't build on Windows at the moment and
it's on my to-do list to set aside a block of time to solve that and
update INSTALL based on what I learn.

But I digress...


> NASM isn't mentioned anywhere in our source tree except here and in
> tools/dev/build-svn-deps-win.pl so probably the right fix is to delete
> this item from INSTALL and perhaps update the comments in
> tools/dev/build-svn-deps-win.pl .
>

NASM isn't mentioned in our source tree because it isn't needed to
build our code.

INSTALL documents it as an optional dependency of a dependency
(OpenSSL).

I wouldn't rush to remove it because I think it's a good thing to have
a list of dependencies (a dependency tree? -- within reason), partly
because one of my pet peeves is trying to build something and then
discovering more and more dependencies along the way. It's nice to
know what I'll need at the outset.

Now, if OpenSSL no longer has this as an optional dependency, then I
agree that it should be removed. I'm looking into it...

Thanks for your input.

Nathan

Re: INSTALL: Grammar advice?

[Julian Foad <ju...@apache.org>]

Nathan Hartman wrote:
> In INSTALL, there is this awkward use of (optionally):
> 
>          The Netwide Assembler (NASM) is used to build the (optionally)
>          assembler modules of OpenSSL.
> 
> Which of these is the best fix?
> 
> (1)     The Netwide Assembler (NASM) is used to (optionally) build the
>          assembler modules of OpenSSL.
> 
> (2)     The Netwide Assembler (NASM) is (optionally) used to build the
>          assembler modules of OpenSSL.
> 
> (3)     The Netwide Assembler (NASM) is used to build the (optional)
>          assembler modules of OpenSSL.

To be blunt: these instructions need a lot more fixing than just grammar.

NASM isn't mentioned anywhere in our source tree except here and in 
tools/dev/build-svn-deps-win.pl so probably the right fix is to delete 
this item from INSTALL and perhaps update the comments in 
tools/dev/build-svn-deps-win.pl .

- Julian