Needs better documentation

[GoogleCodeExporter]

I downloaded the Windows version and found only the executable, config
file, and uninstaller. The Google Code site doesn't even mention that
Mongoose is the successor to shttpd (which is only a little better
documented). There is nothing on Wikipedia.

These days, for software to be accepted, it must have complete and
user-friendly documentation. In fact, many experienced software engineers
(I am one) agree that good, up-to-date documentation is indispensable if
software is to be used by more than one person or is intended to have a
lifetime of more than a few days. Many modern engineers will not even look
at software that is poorly documented.

Mongoose (and shttpd before it) appear to be very useful, filling the vital
role of making almost any computer into a quick-and-limited Web server with
small resource usage. For this reason, Mongoose deserves good
documentation, so it can be used by anyone who needs it.

I realize that programmers outside of the USA may have a different culture,
one in which documentation is seen as obvious or unnecessary. Writing
working code is seen as all that matters. The USA was like that in the
1960's and before. However, we have learned about the importance of good
documentation to make software inviting and useful to everyone and so can you.

I urge you to give these thoughts some consideration, and to take time out
soon to focus on a really good user manual, one that requires a minimum of
previous experience with Web servers, SSL, etc. You will be rewarded by a
fast-growing user community who will praise your software and more
importantly, use it.

David Spector
Springtime Software

Original issue reported on code.google.com by googl...@springtimesoftware.com on 17 Dec 2008 at 2:36

[GoogleCodeExporter]

I should add that I have read the current manual (available on Google Code:
Mongoose). My comments do include that manual. It is too brief, relying on a 
user's
previous experience with Web browsers. Examples of incomplete areas: ways to run
mongoose.exe; examples of serving Web pages that include PHP code or code using 
other
major preprocessors; a complete, step-by-step cookbook for getting Mongoose up 
and
running as a standard Port 80 server, including how to set up Web directories;
Mongoose equivalents to .htaccess files (if any); specific documentation of the
config file format instead of orienting the documentation around command options
(which are not very useful in Windows); a tutorial document on how to set up 
pages
that use SSL and basic authentication; the link to documentation on embedding
Mongoose is mangled and does not work and only points to a brief description on 
the
home page anyway (while I have not tried to write a C++ program that uses 
Mongoose, I
believe I would benefit from more detailed instructions and a test case).

David Spector
Springtime Software

Original comment by googl...@springtimesoftware.com on 17 Dec 2008 at 2:51

[GoogleCodeExporter]

Hi David, thanks for the feedback!
Documentation is to be extended.
I will specifically focus on
  a) embedding. Starting from the next release, DLL will be built on Windows platform
allowing using Mongoose from programs written in other languages (e.g. Visual 
Basic)
  b) novice user
Current manual is targeting experienced UNIX users indeed.

Original comment by valenok on 17 Dec 2008 at 3:20

[GoogleCodeExporter]

Original comment by valenok on 17 Dec 2008 at 3:21

• Changed state: Accepted

[GoogleCodeExporter]

Hi. Thanks for the quick and helpful response.

Thanks for listing the novice user as a future area of expansion for the 
manual. Some
of these folks have never worked with a Web server before. There are lots of 
things
an informal server can do that benefit people using computers (browsers) for all
sorts of things (some working examples would be very useful).

For example, I created a server (using any Web server that can run PHP including
Apache, shttpd, and Mongoose) to run a an important program installed on 
machine A
from machine B located in another city, with security via hashed password. This 
makes
it seem that the program is installed on machine B even though machine B is
prohibited by a too-broad management policy from installing the program 
themselves.
The input is sent from B to A and then the output is sent from A to B. It 
solves a
real-world problem very nicely and securely.

A whole series of servers for various requests can be made. Each is a Web page 
served
by Mongoose (or they can be combined on one Web page). This makes it easy to run
demonstrations, for example, on any computer connected to the Web. They don't 
even
need firewall or other protection, since they use a unique port and only 
respond to
clients who present the proper passwords.

Of course, standalone programs written in server-side programming like PHP 
and/or
Ajax can be run using Mongoose for fast-installing applications or 
demonstrations.
Such applications can run on any expected computer and browser and are easy to
program. These are some of the points, I think, that should be illustrated in 
depth
in a good manual, with a subdirectory of examples.

Embedding is actually not as interesting, since fewer people do it (besides, 
it's not
hard to create a simple Web server in C++ oneself by opening a socket and 
handling
the socket events or messages using the appropriate socket API).

Concerning embedding, it might be good to try to avoid adding a DLL unless you 
truly
need to write code that must run in any process. Anything a simple DLL can do 
can
also be done in the EXE, including (I'm pretty sure) creating an Apartment-type
server with an Automation interface for use from various languages. DLLs almost
always introduce complications in installing, using, uninstalling, and porting 
back
to Linux.

Since I'm giving free advice, try to avoid using the Windows Registry. It makes 
it
harder to move a Mongoose application from computer to computer. Of course, the
Registry must be used when creating an Automation interface, but you could 
easily
make that optional at installation and/or embedding time. Not many embedded
applications really need an Automation interface, or any COM interface at all.

David Spector
Springtime Software

Original comment by googl...@springtimesoftware.com on 17 Dec 2008 at 5:42

[GoogleCodeExporter]

Could you comment on http://code.google.com/p/mongoose/wiki/WindowsUsage , 
please?
I also put together pages documenting API, and embedding strategies, with 
examples.
From now on (since version 2.1), installer creates a README.txt file that 
points to
the WindowsUsage wiki page.
I guess, the wiki page could be a place where people may leave comments with
suggestions, and real life use cases.

Original comment by valenok on 18 Dec 2008 at 11:31

[GoogleCodeExporter]

Original comment by valenok on 19 Dec 2008 at 6:00

• Changed state: Fixed

[GoogleCodeExporter]

Comment on http://code.google.com/p/mongoose/wiki/WindowsUsage: The first 
section, on
installation, is understandable. The second section, on advanced tips, is 
totally
obscure and should be deleted if it can't be turned into clear English.

The manual needs a section on the configuration file, listing each directive 
with
complete description. It also needs either a description of .htaccess files, or 
an
explanation why such files are not supported (such as, to keep Mongoose small). 
It
needs a listing of all detected server error codes and how the user can provide 
a
custom error page.

It needs a detailed list of MIME headers that are accepted by the server.

That's all that comes to mind immediately. Generally, the documentation still 
needs
much more improvement if Mongoose is to be attractive for use by average Web 
programmers.

David Spector
Springtime Software

Original comment by googl...@springtimesoftware.com on 31 Dec 2008 at 4:41

[GoogleCodeExporter]

Five months later: the documentation is much better, particularly for Windows, 
where
Mongoose runs like a charm, either standalone or as a service. Here are some 
suggestions:

1. Publicize it. This tiny file is amazing. It does most of what we use Apache 
for.
It is extremely useful for writing PHP/browser applications. You could also 
supply as
an example a configuration that returns an empty page--this can be used with the
HOSTS file to eliminate embedded ads on Web pages (see details at the Wikipedia
article "Hosts file").

2. Remove the blocks of zeros in the exe file, to make it even smaller. The 
zeros are
not necessary.

3. Provide support for a user file returned on any supported HTTP error.

Original comment by googl...@springtimesoftware.com on 22 May 2009 at 6:42

[GoogleCodeExporter]

Thanks for the feedback.

To reduce the size radically, a static linkage against libc.lib must be changed 
to
dynamic linkage msvcrt.dll, which will bring the exe size from ~150 kb down to 
~45-50 kb.

For custom per-HTTP error files an request
http://code.google.com/p/mongoose/issues/detail?id=48 has been filed recently. 
I plan
to work on that, too.

Original comment by valenok on 22 May 2009 at 7:25

[GoogleCodeExporter]

Manually removing the six blocks of zeros from the Windows version of
mongoose-2.6.exe reduced its size from 151KB to 148KB. And that doesn't include 
the
blocks of garbage left behind by the compiler. There may be compiler and linker
options to optimize for space.

Some Windows users will not have msvcrt.dll available (because they are running 
a
portable or embedded system), but if you are currently statically linking with
libc.lib, you can reduce the size simply by copying the runtime library sources 
or
linked modules that you actually call to your development directory. Then all 
library
calls will be resolved without needing the entire runtime library linked in.

The smaller the executable, the more impressive to prospective users. But, of 
course,
it's up to you whether you want to go to all this trouble.

Original comment by googl...@springtimesoftware.com on 23 May 2009 at 2:39

[GoogleCodeExporter]

Yeah, thanks for the hints.
As far as I know, all Windows systems do have msvcrt.dll, since it is one of 
the core
libraries - a C runtime DLL. Not sure about Windows CE, will check on that 
later.

Original comment by valenok on 23 May 2009 at 5:34

[GoogleCodeExporter]

Nice. A 60KB executable will be very impressive. How will this work on Linux?

Original comment by googl...@springtimesoftware.com on 23 May 2009 at 6:42

[GoogleCodeExporter]

On UNIXes, mongoose is already 40-50kb large.
Example, on my FreeBSD box it is ~40 kb:

devnull@news:~/mongoose$ ls -l mongoose
-rwxr-xr-x  1 devnull  wheel  *39628*  8 фев 22:27 mongoose

On my Linux box, it is also about 40kb:
baton~/mongoose$ ls -l mongoose
-rwxr-x--- 1 lsm eng *41004* 2009-05-22 10:03 mongoose

Original comment by valenok on 23 May 2009 at 7:28

[GoogleCodeExporter]

I don't know if you realize it, but Mongoose is probably the best tiny 
webserver in
existence (the others in Google Code are run in interpreters like Java). See 
also
http://en.wikipedia.org/wiki/Comparison_of_lightweight_web_servers.

Original comment by googl...@springtimesoftware.com on 23 May 2009 at 8:40

[GoogleCodeExporter]

I have just overhauled http://en.wikipedia.org/wiki/Mongoose_(server) to 
describe
Mongoose better. Let me know here if there are any errors or omissions.

Original comment by googl...@springtimesoftware.com on 23 May 2009 at 8:53

[GoogleCodeExporter]

Thanks!

Original comment by valenok on 23 May 2009 at 8:56

[GoogleCodeExporter]

The executable compressor utility UPX was able to compress the mongoose-2.6.exe 
by
47% from 154624 bytes to 73216 bytes.  It has some drawbacks, but anyone who is
interested in smaller executable size could apply it themselves.

See http://upx.sourceforge.net/

Original comment by gilbert....@gmail.com on 26 May 2009 at 3:06

[GoogleCodeExporter]

Ah, cool, I will use it for released executables, thanks for the hint!

Original comment by valenok on 26 May 2009 at 7:06