Changes to create docs.

[MichaelTiernan]

This one is a long one concentrating on the docs.
I made these changes for myself and am offering them back.

1. Fixed spelling in .gitignore.
2. I deleted the output files that can be (or are) generated by the end user.
3. Changed the names of the html versions of the man pages to reflect their inputs.
   epm.1 becomes epm.1.html, etc.
   Also adjusted the .gitignore to not check in the removed files.
4. Changed the size of the book to be US Letter, 8.5x11.
5. Changed the book to include, in the appendix, all the man pages generated.
6. Modified the epm.list to include the generated html pages as part of the documentation.
7. Modified the make process to include creating the docs.
8. Modified the make to allow clean and distclean of the docs.

[michaelrsweet]

@MichaelTiernan I'd like to include the generated documentation files in the repository as not everyone will have HTMLDOC installed to build the documentation. Similarly, a top-level make shouldn't run the documentation makefile...

The 6x9 size was for the book on Lulu.com, although I haven't had a sale of that book in many years (so I should probably just retire it...)

I'm not sure about including the HTML man pages for the file format references, as there is already text in the other chapters for it. But I guess there isn't a simple reference or index of all of the directives so maybe that makes sense after all...

Including the man page section in the generated HTML filenames doesn't seem necessary - personal preference or something else you are concerned about?

[MichaelTiernan]

I should have prefaced that whole thing with "lots of personal preference involved here" 😄

You're right about keeping the pregenerated docs there. Better choice. My only desire would be that they not be overwritten by me doing a make and generating new ones then. Just a preference thing.

Similarly, a top-level make shouldn't run the documentation makefile...

Counter point being that a make all at the top level should, by definition make all and if the documentation is part of the end package, then that's included in the definition of 'all'.

I guess I'd say then that the Makefile in doc (which is created by the config process implying that something is there that can be made.) should default on make or make all to simply check that all the targets are there and if they aren't, say something. Otherwise, require something like a make force to trigger a regeneration of the outputs.

I'll concede the point since it's your product and your judgement which defines the choices made. Just offered as a thought.

Including the man page section in the generated HTML filenames doesn't seem necessary - personal preference or something else you are concerned about?

A little of both. I'm a firm believer in making the infile -> outfile naming consistent. froboz_corp_profit_statement.md should not become profits.{html|pdf} (etc.)

In this case, seeing epm.html in a documentation directory, I'd expect to find a document about the entirety of the epm 'product' and not just the manpage (which I've probably already read and am looking for more info beyond that.) which will result in frustration requiring more hunting. The name epm.html implies what is actually delivered by epm-book.html but that's not obvious unless I see the book entry before the html file.

My inclusion of the html versions of the manpages in the book output is because I now have printed the book and stuck it in a simple binder and that now includes all the manpage outputs as my backup so I can reference them while working. (Damn screens are getting smaller and it's hard to keep two windows open at the same time.)

Again, just my opinions.

Thanks for listening.