835486 - Provide initial documentation for NSS tools (both as HTML and Unix-style man-pages format)

Status: RESOLVED FIXED

(NSS :: Documentation, defect)

Description

[Kai Engert (:KaiE:)]

On Linux, we should provide Unix-style manual pages for the NSS tools, e.g. "man certutil" should work.

I notice that https://developer.mozilla.org/en-US/docs/NSS_reference/NSS_tools
exists.
I don't know if any of that text had already been written in a format suitable for manpages?

I personally would prefer authoring the manpages in a simple style, close to plaintext - and ideally something that could be easily converted into both the built-in usage output of our tools, and also for the man pages.

One approach to create man pages using ASCII is the following:
- use asciidoc format for authoriting a file certutil.1.txt
  (see http://www.methods.co.nz/asciidoc/ )
- run: 
  asciidoc.py -d manpage -b docbook certutil.1.txt
- run:
  xsltproc --nonet /usr/share/asciidoc/docbook-xsl/manpage.xsl certutil.1.xml

An example input file can be found at
https://fedorahosted.org/nss-gui/browser/wrapnssgui/nss-gui.1.txt

(And on Fedora, install the nss-gui package and type "man nss-gui" to see how the output will look like).

I propose:
- convert the existing NSS man pages from 
  https://developer.mozilla.org/en-US/docs/NSS_reference/NSS_tools
  into this format
- add an OPTIONAL makefile target to NSS,
  that will execute the above commands to produce man pages,
  and require that the tools are installed
- change Fedora spec scripts to do that by default and include the man pages

Comment 1

[Ryan Sleevi]

Your proposal is unclear, but as I interpret its intent, it's not something I'd support.

The reason for this is man pages do not help users on other platforms - such as Mac and Windows - while the web pages do.

While I certainly support having better documentation, and certainly appreciate having a single documentation source, any proposal that requires both modifying man pages and web pages on changes simply increases the work and creates more headache for documentation.

If you're proposing to convert all the web pages into canonical documentation forms, and then generate (man pages || web pages) with each NSS release, then I think that's a fine and admirable idea. But if you're proposing creating yet-another-set of documentation to maintain, then I think in the long run, that will be worse, not better.

Comment 2

[Kai Engert (:KaiE:)]

(In reply to Ryan Sleevi from comment #1)
> Your proposal is unclear

Because I'm not yet sure what we should do.

But we should have some kind of man pages, because that's what people expect on Linux. I'm flexible how we produce them.

I agree that having external man pages, which are fully synchronized with the usage output printed by tools at runtime, is a challenge. I'm not ready to work on that. But I want to invite everyone to contributes ideas what to do.

I agree the web output is more important than the man pages, because man pages are Linux only, while everyone can access the web pages.

But how about the following first step: We could convert the existing web pages to the "asciidoc" format, that should require only a small amount of work. Once we have that, we can easily render that for both static web pages and for man pages (because asciidoc offers that). What do you think?

Comment 3

[Kai Engert (:KaiE:)]

Attachment: example html output, produced using asciidoc tool

FYI, just to show how it looks like, I took the above example file in asciidoc format
  https://fedorahosted.org/nss-gui/browser/wrapnssgui/nss-gui.1.txt

and used this command to convert it to html:
  asciidoc.py -d article -b xhtml11 nss-gui.1.txt

and it produced the attached output HTML (click attachment to view it).

Comment 4

[Kai Engert (:KaiE:)]

Attachment: example manpage output (just the text without the highlighting), produced using asciidoc tool

Comment 5

[Ryan Sleevi]

I have no context to evaluate the merits of asciidoc as a format. My only experience with auto-generated HTML from man pages has been with OpenSSL's man pages, which I consider something we should try to avoid (for both formatting and accessibility). I'm also concerned (but again, have no experience) that asciidoc will significantly limit us in the ability to be both expressive in the documentation and to cross-reference documentation.

I'm also not convinced that simply because man pages are expected that they're the best approach for the project - if this would help Linux but hinder Mac/Win/Android, or make it even harder to maintain documentation, then I don't think that's good either. I also don't know if it's a good idea to essentially "split" the documentation - that which is maintained on the wiki and that which is maintained via CVS.

These are just some of the 'costs' associated with switching to asciidoc. In order to evaluate whether the change is good, the 'benefits' should outweigh the costs. The only benefit I've seen is that "Linux users expect it", and while not trying to snub anyone, I'm not sure if that's a compelling enough benefit on its own.

To be clear: I *am* supportive of making our documentation better, more accessible, and easier to use - not to mention ensuring that it reflects 'reality'. This is the same reason I support doing the release notes and making sure we highlight things properly. But I want to avoid a situation where we simply switch forms because (some small reason X), and then it becomes harder to write or maintain documentation on any system (but Linux, presumably).

Comment 6

[Elio Maldonado]

See also: https://developer.mozilla.org/en-US/docs/NSS_reference/NSS_tools
Still a work in progress or lack off to be more accurate.

Comment 7

[Kai Engert (:KaiE:)]

(In reply to Elio Maldonado from comment #6)
> See also: https://developer.mozilla.org/en-US/docs/NSS_reference/NSS_tools

Yes, I mentioned it as the first link in this report :)

Comment 8

[Kai Engert (:KaiE:)]

I don't have the energy to respond to each of Ryan's concerns in detail.

Let me say in general, the more constraints you add for creating documentation "the right way", the less likely it is that we get any documentation at all.

I haven't suggested that we "auto generate html based on man pages", I've suggested that we use asciidoc - which is a plain text format, which can be used as the master, and from which either manpages or html output can be generated.

I looked at Elio's link again, and I realize that those documentation wasn't written in html format in the first place either. It was written using docbook xml, and that already allows to produce both man pages and html output.

In other words, in theory, my problem could have been already solved in year 2010, when those apparently documents got updated the last time. I don't understand why those man pages never got added to the Linux packaging at least? Maybe because of the thought it was incomplete? Or because of other resistance?

Whatever the reason, I'm worried that having a docbook xml master format isn't helping us very much. There are too many details to worry about. We don't have someone dedicated to maintaining out documentation. I couldn't find a working free-software editor for docbook format files (both "beacon" and "vex" each had their own problems which caused them to no work for me). I'm not motivated to edit xml files using an ascii editor.

I believe we are in agreement that, ideally, we should have just one place where all our documentation resides. I have an idea, and I'll describe that idea in the next comment.

Comment 9

[Kai Engert (:KaiE:)]

I propose to define the source code of our tools to be the one and only location that contains documentation for the command line usage.

I propose that we enhance our tools to print the usage documentation in multiple formats.

In other words:
- by default the tools print the classic ASCII help
- using an optional command line switch like --docs
  the tools print documentation in a format that is suitable for further processing
  and conversion into other output formats, like man pages and html.

I propose to hide the complexity of the "man" and "html" documentation formats from our tools, and rather, have the --docs output be a very simple ascii based format. I propose that we investigate if "asciidoc" is sufficient for this purpose.

How could this look like?

In our source code, instead of simply using strings, we could define the usage otions as an arrays of strings. One array per logical documentation section, whenever an array makes sense. For example: name (string), synopsis (string), description (string), options (array of strings), etc.

We invent trivial ascii markup that can be easily searched/replaced/removed, to support the few structuring attributes that we need.

Now I'm worried that you still find it difficult to follow my thoughts. Maybe it's necessary to produce an example.

Comment 10

[Paul Wouters]

For openswan/libreswan, we use XML files and xmlto to create man pages and html pages from the same source. The usage/--help is documented at the top (as is usual for man pages) but also present for any binary using the -h/--help. So while the usage exists in two places, the full man page text only exists in one place. If someone cares enough, the usage for binaries could be generated from the XML and incorporated into the source of individual commands.

This all started with me trying to figure out how to some things with certutil. I could not find a man page, and the -h usage when scanned did not help me. Only much later did i realise the -H. And even then, piping -H into 'less' produced just the last page of output, adding to the confusion.

Comment 11

[Elio Maldonado]

Kay said: > Yes, I mentioned it as the first link in this report :)
oops, ... and you refer to it in subsequent comments, it pays to read the threads from the very start :-)

XML coupled with docbook lends itself to integrating with a book , if someone in the future would want to produce one on security tasks, and that was the primary reason I chose it. There are numerous open source and cross-platform supporting tools. We should definitely explore asciidoc as Kai suggested. 

It is my opinion that the man pages effort properly belongs here rather than in fedora. It's the wealth of options in certutil that needs addressing and once that is done the rest of the tools should be a lot easier.

Comment 12

[Kai Engert (:KaiE:)]

In an effort to push this forward, I spent the afternoon with exploring.

I found "pandoc" which can be used to convert the existing docbook files that Deon and Elio had created to asciidoc! If we chose to use asciidoc as the master format, we'd still be able to produce docbook output.

(Some detailed markup gets replaced with more general markup, for example, <command> gets replaced with <literal>.)

But comparing the manpages

(a) docbook -> xmlto -> manpage
(b) docbook -> pandoc -> asciidoc -> docbook -> xmlto -> manpage

the (b) result still looks very close to the original, the only different I noticed is that the "bold highlighting of certutil" throughout the manpage got lost.

Comment 13

[Ryan Sleevi]

(In reply to Kai Engert (:kaie) from comment #8)
> I don't have the energy to respond to each of Ryan's concerns in detail.

This is unfortunate.

> 
> Let me say in general, the more constraints you add for creating
> documentation "the right way", the less likely it is that we get any
> documentation at all.

Yes, rules make things harder. This is true whether you're talking about requiring changes be licensed appropriately (eg: MPL2), having style guides, requiring code be reviewed, or having minimum standards for secure coding.

The goal of the project should not be to chump in any change that people want, simply because someone is willing to do the work, but to try and provide guidance or criteria on the path forward.

I'm not opposed to generating man pages at all. But I believe that whatever solution we take for man pages should be consistent with our overall plan for documentation.

If the solution is "Every time you change a flag, you have to update 7 different documents", then it will do one of the following: a) Discourage people from ever making any changes (because the overhead of maintaining documentation is high) or b) Create subtle documentation bugs where someone updates some locations, but not all.

I'm simply requesting that in the quest to improve the *Nix user experience (by providing man pages, a perfectly reasonable request) that you don't unduly burden other developers by creating new sources of documents to maintain.

> 
> I haven't suggested that we "auto generate html based on man pages", I've
> suggested that we use asciidoc - which is a plain text format, which can be
> used as the master, and from which either manpages or html output can be
> generated.
> 
> I looked at Elio's link again, and I realize that those documentation wasn't
> written in html format in the first place either. It was written using
> docbook xml, and that already allows to produce both man pages and html
> output.

Yes, docbook xml works quite well for a number of open source projects, and allows the creation of both rich HTML documentation and rich man pages. Given how widely it's used in the OSS community, I suspect it may be a better proposal to consider xmldoc, rather than asciidoc.

> 
> In other words, in theory, my problem could have been already solved in year
> 2010, when those apparently documents got updated the last time. I don't
> understand why those man pages never got added to the Linux packaging at
> least? Maybe because of the thought it was incomplete? Or because of other
> resistance?
> 
> Whatever the reason, I'm worried that having a docbook xml master format
> isn't helping us very much. There are too many details to worry about. We
> don't have someone dedicated to maintaining out documentation. I couldn't
> find a working free-software editor for docbook format files (both "beacon"
> and "vex" each had their own problems which caused them to no work for me).
> I'm not motivated to edit xml files using an ascii editor.

While a perfect valid concern, I think we should be looking at the overall merits of the documentation schemes (online-only, xmldoc, asciidoc), rather than simply writing off solutions on this basis.

> 
> I believe we are in agreement that, ideally, we should have just one place
> where all our documentation resides. I have an idea, and I'll describe that
> idea in the next comment.

Comment 14

[Elio Maldonado]

We should integrate the production of the man pages with build system on not be a separate activity. That way a developer that modifies one the tools is more likely to update the master documentation sources to reflect the changes being made. In fact, I could go a step further and require it as part of the patch submission send for review when any changes made would affect documentation.

Comment 15

[Kai Engert (:KaiE:)]

(In reply to Ryan Sleevi from comment #13)
> I'm not opposed to generating man pages at all. But I believe that whatever
> solution we take for man pages should be consistent with our overall plan
> for documentation.

We do have an overall plan? :) I didn't know.


> If the solution is "Every time you change a flag, you have to update 7
> different documents"

I'm sorry if I gave that impression. I fully agree this doesn't work.

My point was:
- we already have 2 sets of documentation, built-in and external
- the external docs apparently got never shipped and are no longer current
- let's convert the external docs to something that is multi-purpose,
  and using a very simple format.

Your proposal to use docbook or to use xmldoc might be smart, but will it be practical? I don't know anything about xmldoc, couldn't even find it after you mentioned it, but in my opinion using docbook is too complicated for quick editing. If there were a free and good editor available, that wouldn't require one to manually think about the nesting of the xml documents, that might be a different story. But today I couldn't find such an editor.

I believe that using a simple ASCII based format has the highest chances to actually get updated whenever programmers adjust the code - because then updating the documentation will be trivial.

That's why my initial proposal in this bug was, let's have two sets, the built-in, and exactly one external format, that can be trivially updated, and be used to genrate other docs.


Then I learned that we *already* had the ability to auto-generate various documentation formats already, since 2010, because we already had manpages, this reconfirmed my theory - that editing those docbook xml files were too much work for people to bother.


> I'm simply requesting that in the quest to improve the *Nix user experience
> (by providing man pages, a perfectly reasonable request) that you don't
> unduly burden other developers by creating new sources of documents to
> maintain.


That's exactly what I want to avoid. The question is, do you think that 2 places (built-in plus one external document) are a good number of places, or is 2 places even too difficult already? I'm worried it's indeed too different to maintain already (given our little resources).

And that's why I had adjusted my proposal in the following comment.
My latest proposal is to have only place for the usage documentation: Inside the code. And have shared code in cmd/util that can print our internal usage documentation in two output styles - standard plain text usage (classic tool output) - plus asciidoc output, which we could use as input for all other desired formats.


> Yes, docbook xml works quite well for a number of open source projects, and
> allows the creation of both rich HTML documentation and rich man pages.
> Given how widely it's used in the OSS community, I suspect it may be a
> better proposal to consider xmldoc, rather than asciidoc.

Why is it better?
Just because other people use it doesn't convince me that it's best for our needs.


> While a perfect valid concern, I think we should be looking at the overall
> merits of the documentation schemes (online-only, xmldoc, asciidoc), rather
> than simply writing off solutions on this basis.

I don't have time for a research project. You're certainly welcome to focus on such a project :) I'm simply attempting to get something done, trying a quick approach, that doesn't distract me too much from other important work.

Comment 16

[Ryan Sleevi]

(In reply to Kai Engert (:kaie) from comment #15)
> (In reply to Ryan Sleevi from comment #13)
> > I'm not opposed to generating man pages at all. But I believe that whatever
> > solution we take for man pages should be consistent with our overall plan
> > for documentation.
> 
> We do have an overall plan? :) I didn't know.
> 
> 
> > If the solution is "Every time you change a flag, you have to update 7
> > different documents"
> 
> I'm sorry if I gave that impression. I fully agree this doesn't work.
> 
> My point was:
> - we already have 2 sets of documentation, built-in and external
> - the external docs apparently got never shipped and are no longer current
> - let's convert the external docs to something that is multi-purpose,
>   and using a very simple format.
> 
> Your proposal to use docbook or to use xmldoc might be smart, but will it be
> practical? I don't know anything about xmldoc, couldn't even find it after
> you mentioned it, but in my opinion using docbook is too complicated for
> quick editing. If there were a free and good editor available, that wouldn't
> require one to manually think about the nesting of the xml documents, that
> might be a different story. But today I couldn't find such an editor.
> 
> I believe that using a simple ASCII based format has the highest chances to
> actually get updated whenever programmers adjust the code - because then
> updating the documentation will be trivial.
> 
> That's why my initial proposal in this bug was, let's have two sets, the
> built-in, and exactly one external format, that can be trivially updated,
> and be used to genrate other docs.
> 
> 
> Then I learned that we *already* had the ability to auto-generate various
> documentation formats already, since 2010, because we already had manpages,
> this reconfirmed my theory - that editing those docbook xml files were too
> much work for people to bother.
> 
> 
> > I'm simply requesting that in the quest to improve the *Nix user experience
> > (by providing man pages, a perfectly reasonable request) that you don't
> > unduly burden other developers by creating new sources of documents to
> > maintain.
> 
> 
> That's exactly what I want to avoid. The question is, do you think that 2
> places (built-in plus one external document) are a good number of places, or
> is 2 places even too difficult already? I'm worried it's indeed too
> different to maintain already (given our little resources).
> 
> And that's why I had adjusted my proposal in the following comment.
> My latest proposal is to have only place for the usage documentation: Inside
> the code. And have shared code in cmd/util that can print our internal usage
> documentation in two output styles - standard plain text usage (classic tool
> output) - plus asciidoc output, which we could use as input for all other
> desired formats.
> 
> 
> > Yes, docbook xml works quite well for a number of open source projects, and
> > allows the creation of both rich HTML documentation and rich man pages.
> > Given how widely it's used in the OSS community, I suspect it may be a
> > better proposal to consider xmldoc, rather than asciidoc.
> 
> Why is it better?
> Just because other people use it doesn't convince me that it's best for our
> needs.
> 
> 
> > While a perfect valid concern, I think we should be looking at the overall
> > merits of the documentation schemes (online-only, xmldoc, asciidoc), rather
> > than simply writing off solutions on this basis.
> 
> I don't have time for a research project. You're certainly welcome to focus
> on such a project :) I'm simply attempting to get something done, trying a
> quick approach, that doesn't distract me too much from other important work.

This approach is not helpful if you're asking other developers / the project to adopt the change. The burden of establishing it as a better solution falls to the person proposing.

Perhaps my request was worded wrong, a different way to say it is:

We have the following requirements that are trivially identified:
- We want man pages for Linux
- We want to avoid multiple sources of documentation
- We want documentation to be available on the web for users of systems that don't have man pages

There may be additional, implicit requirements that we're further operating on with the web page documentation. We should gather those first.

We should then ask "What's the best way to meet those".

My concern is that you're approaching this primarily with a solution in mind (asciidoc), which can certainly solve a problem at hand (generate man pages), but your replies leave me concerned that you may not be considering the other (implicit or explicit) requirements - whether they be features we must have or recognition of features we'd lose from our existing "solution".

Think of how you might respond if someone proposed replacing our test infrastructure with C++ (as, incidentally, has been done offhand in the past). While it could certainly make some things easier (eg: easy *Unit-style XML results), it has a new set of tradeoffs - and those have to be evaluated.

Comment 17

[Ryan Sleevi]

(In reply to Elio Maldonado from comment #14)
> We should integrate the production of the man pages with build system on not
> be a separate activity. That way a developer that modifies one the tools is
> more likely to update the master documentation sources to reflect the
> changes being made. In fact, I could go a step further and require it as
> part of the patch submission send for review when any changes made would
> affect documentation.

A HUGE +1 from me on this. This is exactly what my 'ideal' solution looks like as well.

Comment 18

[Kai Engert (:KaiE:)]

(In reply to Ryan Sleevi from comment #17)
> (In reply to Elio Maldonado from comment #14)
> > We should integrate the production of the man pages with build system on not
> > be a separate activity. That way a developer that modifies one the tools is
> > more likely to update the master documentation sources to reflect the
> > changes being made. In fact, I could go a step further and require it as
> > part of the patch submission send for review when any changes made would
> > affect documentation.
> 
> A HUGE +1 from me on this. This is exactly what my 'ideal' solution looks
> like as well.

Are the necessary tools for generating documentation even available on each platform where we build?

I was assuming that only certain environments have easy access to the full set of tools, and that it would be sufficient to have a separate makefile target for them.

Nevertheless, updating the documentation could still be made a requirement for patches that update the tools.

Comment 19

[Kai Engert (:KaiE:)]

(In reply to Ryan Sleevi from comment #16)
> Perhaps my request was worded wrong, a different way to say it is:
> 
> We have the following requirements that are trivially identified:
> - We want man pages for Linux
> - We want to avoid multiple sources of documentation
> - We want documentation to be available on the web for users of systems that
> don't have man pages
> 
> There may be additional, implicit requirements that we're further operating
> on with the web page documentation. We should gather those first.
> 
> We should then ask "What's the best way to meet those".
> 
> My concern is that you're approaching this primarily with a solution in mind
> (asciidoc), which can certainly solve a problem at hand (generate man
> pages), but your replies leave me concerned that you may not be considering
> the other (implicit or explicit) requirements - whether they be features we
> must have or recognition of features we'd lose from our existing "solution".


In my understanding, my proposal does satisfy all your requirements.

- asciidoc can produce man pages
- asciidoc can produce html pages (for the web)
- asciidoc can produce docbook, so can you generate other formats, too
- I want to have a single place of usage documentation, by integrating it into the
  code.

Which part of that is it that you think doesn't match the requirements?

Comment 20

[Kai Engert (:KaiE:)]

Attachment: Patch v1 - use "pp" as an example

This patch does multiple things:

- it adds new general purpose types and functions
    struct option_usage_struct;
    void printPlainUsage(const char *progName);
    void printAsciiDoc(const char *progName);
  and some general helper functions
    void print_synopsis(const char *progName);
    void print_styled_text(unsigned int max_chars, PRBool asciidoc,
                           const char *txt);
    void print_wrapped_indented_styled_text(unsigned int indent, 
                                            PRBool asciidoc, 
                                            const char *txt)

  The general purpose functions are intended to become part of 
  security/nss/cmd/lib making them available for all tools.

- variable definitions specific to the "pp" utility:
    const char *doc_oneliner;
    const char *doc_description_styled;
    struct option_usage_struct option_usage[];
    const char *doc_static;
    const char *usage_synopsis;

The above code demonstrates a framework, and I propose to convert all tools, integrating the manpages that have been written three years ago.

When running the above code without parameters
  pp
the following standard output will be generated:

Usage:
pp -t type [-a] [-i input] [-o output]
-t type   Specify the input type (must be one of private-key, public-key,
          certificate, certificate-request, certificate-identity,pkcs7, crl,
          name)
-a        Input is in ascii encoded form (RFC1113)
-i input  Define an input file to use (default is stdin)
-o output Define an output file to use (default is stdout)


When running
  pp --asciidoc
it will produce output in the asciidoc format,
I'll attach that output as file pp.1.txt

I'll also attach the output of
  asciidoc.py -d manpage -b docbook pp.1.txt
  xsltproc --nonet /usr/share/asciidoc/docbook-xsl/manpage.xsl pp.1.xml
as file pp.1
(you may download it and view it using "man ./pp.1")

I'll also attach the output of
  asciidoc.py -d article -b xhtml11 pp.1.txt
as file pp.html which may view directly in the web browser.

Comment 21

[Kai Engert (:KaiE:)]

Attachment: pp.1.txt - automatically created documentation in asciidoc format

Comment 22

[Kai Engert (:KaiE:)]

Attachment: pp.1 - Unix manual page created using asciidoc

Comment 23

[Kai Engert (:KaiE:)]

Attachment: pp.1 - HTML documentation created using asciidoc

Comment 24

[Kai Engert (:KaiE:)]

Note that I wrote code that allows us to embed asciidoc style into the code, by wrapping it inside {{ and }}. Such statements will be removed when printing plaintext, and the inside statements will be kept when writing asciidoc. See the {{*}} and {{_}} example sections.

Comment 25

[Kai Engert (:KaiE:)]

Ryan, does this seem like an improvement, compared to what we have today?

With this approach, the "usage" of our tools needs to get documented only in one place.

Additional documentation can be directly embedded into the sourcecode - or - if desirable, the static section (examples, explanations that are separate from the parameters) could be easily placed into a separate non-code file, that could be read and integrated from inside the code.

Comment 26

[Kai Engert (:KaiE:)]

Attachment: plain text output

based on asciidoc's xml file, this plain text output was created using
  xmlto -o txt txt pp.1.xml

Comment 27

[Kai Engert (:KaiE:)]

Attachment: docbook output

Comment 28

[Kai Engert (:KaiE:)]

Comment on attachment 707829 [details] [diff] [review]
Patch v1 - use "pp" as an example

Before I ask for review, let me ask for some high level feedback on the patch first.

The final patch should move the general purpose functions to security/nss/cmd/lib and use additional parameters for the tool specific strings and usage array.

Comment 29

[Rich Megginson]

How hard will this be for non-coders (e.g. a doc writer) to update?  Does this mean that it will be up to the developers to maintain the docs from now on?

Comment 30

[Ryan Sleevi]

(In reply to Kai Engert (:kaie) from comment #25)
> Ryan, does this seem like an improvement, compared to what we have today?

No.

> 
> With this approach, the "usage" of our tools needs to get documented only in
> one place.

I'm concerned about *adding more places*, not with trying to find a grand unified documentation scheme.

I have no objection to - and in fact, a strong preference for - having minimal documentation available via some -?/-h/--help flag, and full explanation, context, and details available via some form of permanent documentation.

That is: Two places to document.

Putting the documentation in source code, in my mind, is a significant step back:
1) It ends up linking the total documentation into the final binary, rather than allowing it to be removed, stripped, etc (eg: I previously worked on systems where we were creating a final image and intentionally removed man pages to preserve size. We do this on ChromeOS as well)

2) It requires that anyone wanting to write or maintain documentation must be a coder.

3) It provides little ability to do semantic checking of the correctness of the documentation, short of recompiling binaries and then further re-generating documents. Any failures require recompiling binaries. That is not good nor desirable.

> 
> Additional documentation can be directly embedded into the sourcecode - or -
> if desirable, the static section (examples, explanations that are separate
> from the parameters) could be easily placed into a separate non-code file,
> that could be read and integrated from inside the code.

Again, to emphasize, I support solutions like what Elio was already doing, in creating a set of documents that can be used to generate man pages.

My opposition is:
1) Having these auto-generated files (whether docbook or asciidoc) be something has to be maintained *in addition to* the existing web pages and binaries, or creating a system where "some" of the documentation is in one place and "some" of the documentation is in another.
3) asciidoc is a much more limiting and uglier solution than our existing web page documentation, and thus we sacrifice a lot of flexibility

Comment 31

[Elio Maldonado]

Comment on attachment 707829 [details] [diff] [review]
Patch v1 - use "pp" as an example

Though I like the end results I must say it the means to the end are bit complex as I look at the code. Even moving some of the generic functions to the sectools library there would be quite a bit to more complex tools such as certutil. I do share the concern expressed by Rich and Ryan regarding contributions by non-developers.

Comment 32

[Elio Maldonado]

(In reply to Kai Engert (:kaie) from comment #18)
> Are the necessary tools for generating documentation even available on each
> platform where we build?
> 
xmlto, to use at build time to the conversions hosted at https://fedorahosted.org/xmlto/ 
is available on most major distributions. Fedora and the debian based ones, e.g. Unbuntu and Mint. There is a port to Mac OS X but not as developer friendly as I would like. I'm trying to build myself and brings in some dependencies that complicates things a bit. Granted, my Mac skills have become rusty.

The other tool we used is the "XML Copy Editor" - http://xml-copy-editor.sourceforge.net
I used that tot so much to edit but to validate the XML. It' available on most Linux distrubutions, Windows, but not on Mac OS X as far as I know. That's for interactive use, xmlto is the one that matters as far as the desire to generate and convert formats at build time goes.

Comment 33

[Kai Engert (:KaiE:)]

> How hard will this be for non-coders (e.g. a doc writer) to update?  
> Does this mean that it will be up to the developers to maintain the docs from now on?

If we moved the static portions of the documentation to separate plain text files (as I've suggested in my previous comment), then non-programmers would still be able to contribute. I believe the bar for contributing would be even lowered, because editing in asciidoc format is much simpler than editing in docbook format.


But yes, for the syntax part (the lines at the top of the documentation) and for the parameter description part, the help of a programmer would be required to add those snippets.

I'd say that's an acceptable limitation, given the benefit that using this approach, programmers are automatically keeping the documentation in sync, by having to write a description text just once.


And what value is having separate documentation:
- if apparently no doc writer has made any contribution since November 2010,
  while lots of options have been added/removed in the meantime?
- if programmers forget about updating, 
  like Elio forgot in bug 807890 and like Ryan forgot in bug 816853 ?
- if some programmers aren't even aware of the external documentation,
  like I wasn't when I added crlutil -S in bug 728044 ?

If the documentation were created by the code, we wouldn't have forgotten.

Comment 34

[Kai Engert (:KaiE:)]

Comment on attachment 707829 [details] [diff] [review]
Patch v1 - use "pp" as an example

But if nobody supports my suggestion, fine, let's drop it.

Comment 35

[Kai Engert (:KaiE:)]

Elio, can we check in the existing xml files into new subdirectory mozilla/security/nss/doc ?

I looked at xmlcopyeditor, that one looks better than all the other tools I had seen before, thanks.

Comment 36

[Kai Engert (:KaiE:)]

Attachment: manpagesnss.git - Patch to add missing, recently added options

Elio, this is a patch for your git from
  git://fedorapeople.org/~emaldonado/manpagesnss.git

It adds the recently added new options, see the bug numbers I mentioned in the previous comment.

Not for check in to NSS - but only for your git.

I'll suggest a separate patch for NSS CVS.

Comment 37

[Kai Engert (:KaiE:)]

Attachment: Patch - add the existing docbook manpages to NSS CVS

Elio,

this patch simply contains what you have published at
  git://fedorapeople.org/~emaldonado/manpagesnss.git

and adds it to
  mozilla/security/nss/doc/
including the Makefile you had created.

I'm not yet adding it as a default build - I think that should be done in a separate, future step - after we have worked out on which systems we want to build that by default (for example, we cannot build easily on Android etc.).

This patch would solve my needs.

In Linux packaging, a distribution could explicitly build this new directory as part of their packaging, and pick up the resulting man pages for inclusion in a package.

Comment 38

[Rich Megginson]

As long as it is easy for a non-coder to work on the docs (even though this is a rare occurrence), this is fine.  It should be easy for a developer to update the docs when updating the code for the "UI" (which in this case is the command line interface/switches).  It should be easy to produce man pages and web based documentation.

So, works for me.  It sure will be nice to have NSS man pages.

Comment 39

[Elio Maldonado]

Comment on attachment 708105 [details] [diff] [review]
manpagesnss.git - Patch to add missing, recently added options

Review of attachment 708105 [details] [diff] [review]:
-----------------------------------------------------------------

Thank you Kai. r+ and pushed to git.

Comment 40

[Elio Maldonado]

(In reply to Kai Engert (:kaie) from comment #37)
> Created attachment 708107 [details] [diff] [review]
> Patch - add the existing docbook manpages to NSS CVS
> 
> Elio,
> 
> this patch simply contains what you have published at
>   git://fedorapeople.org/~emaldonado/manpagesnss.git
> 
> and adds it to
>   mozilla/security/nss/doc/
> including the Makefile you had created.
> 
> I'm not yet adding it as a default build - I think that should be done in a
> separate, future step - after we have worked out on which systems we want to
> build that by default (for example, we cannot build easily on Android etc.).
> 
> This patch would solve my needs.

and mine plus many downstream package maintainers needs :-)

> 
> In Linux packaging, a distribution could explicitly build this new directory
> as part of their packaging, and pick up the resulting man pages for
> inclusion in a package.

It would be very easy. If if weren't for the fact that some of the tools descriptions still need  review and certutil needs quite a bit cleanup, I would recommend checking it in. This is usefull whether a Linux ditro or us here opt for assciidoc or xml as the master format.

Thank you Kai.

Comment 41

[Ryan Sleevi]

I have attempted to resolve these concerns privately with Kai, but he has indicated that he is unwilling to attempt to work with me to find a solution that addresses these concerns, and has indicated that unless I'm willing to do this all myself, he plans to move forward.

I believe this is bad for the project, and bad for individual behaviour, and extremely unprofessional.

My concerns with Kai's docs-in-files proposal are many, and I will repeat them for the sake of others, who I hope will convince Kai that his approach is bad:

1) In order to generate documentation, it forces a developer to build binaries and execute them, to output asciidoc. As Brian Smith has discussed in numerous bugs (such as Bug #772144, Bug #815912, Bug #784316), the NSS cross-compilation setup is already bad (in requiring the host nsinstall). Baking such further assumptions that binaries can be run during building is not an acceptable solution to me.
2) By placing documentation in code, it increases the appeal of and risk of using pre-processor macros as part of the documentation. Even a macro as simple as "#ifdef FOO" that conditionally included documentation would lead to inconsistent documentation based on the flags used to compile something. Combined with #1, which requires that documentation be generated using a build compatible with the host machine, this is not good.
3) By placing documentation in code, it significantly increases the burden for non-developers to maintain or contribute documentation and code. It does not reduce there being "two places for documentation", since there will still need to be non-flagged documentation - but it places significant chunks on either side, including long/formal descriptions.
4) By placing documentation in code, it strongly favour's Kai's preferred asciidoc solution, which creates significant hurdles to any further improvements, such as using the (quite common & successful) Docbook format, as used by Elio.
5) The asciidoc format Kai prefers is significantly limited in expressiveness and syntax, and while it may be preferable to Kai, I think it's a net-loss. A format such as docbook focuses on the semantic meaning of the content, rather than the asciidoc emphasis on presentation, and as a result, it allows for much more documentation to be expressed.
6) The inclusion of the documentation in production binaries means that projects (such as ChromeOS) cannot simply 'opt out' of including documentation when running in constrained or limited environments.


I see our documentation goals as such (with no particular priority)
1) We want better documentation
  a) For end users
  b) For developers USING NSS
  c) For developers CONTRIBUTING to NSS
2) We want man pages on Linux (supports 1.a, and, depending on how we do it, 1.b)
3) We do not want to have lots of documentation scattered about (as we do already for release notes, build instructions, API documentation, design docs, etc)
4) We do not want documentation to be hard to maintain
  a) For non-developers who want to improve the documentation but may not be able to contribute code
  b) For developers working on the project who may need to document changes and improvements
5) [Ideally] Our documentation should be able to be localizable, so that it can support 1

I'm sure there are more that I missed that Bob, Elio, Brian, Wan-Teh, and others may have. I suggested that Kai should talk to the NSS developer community before going too far forward with his proposal, to make sure that his proposal took into consideration the concerns.

I am not asking Kai to come up with the grand unified solution for all of this. I am asking that he consider how well his proposal aligns with some of these goals, and if there are changes that can be made that make it easier, rather than harder, to meet these goals. This is especially true because if the proposal as forward goes through, it will be significantly harder to change - both in practice and because this introduces a 'public' API point for dumping documentation.

I have indicated that I'm willing to *work together* for a solution, but that I do not have time to engage in a "design battle" where I propose and implement a complete counter-solution, taking over this bug for Kai.

I think the work Elio has done is a much better proposal, not the least because Docbook represents a much better format for improving the documentation overall.

The solution, as proposed, remains a strong r- from me, because I think we can do better, both short-term and long term, and I do not believe it's a significant hardship to request this.

Comment 42

[Kai Engert (:KaiE:)]

(In reply to Ryan Sleevi from comment #41)
> 
> I believe this is bad for the project, and bad for individual behaviour, and
> extremely unprofessional.

I think this isn't fair, because as you can see in the bug, I have instead followed up to enhance the docbook documentation.

Comment 43

[Robert Relyea]

We should also be clear:

While I agree we need to enhance the documentation for contributers and developers, this bug is basically about NSS tools documentation (not API) documentation. I'm agnostic about how we do this, but we need to be able to convert whatever we have into Linux man pages, since Linux is the only platform anyone actually ships tools on. I believe all proposals described here provide that. I'm prefectly happy with Elio and Kai's docbook proposal. I presume Ryan is as well.

Comment 44

[Ryan Sleevi]

To be clear:
+1 docbook.
-1 docs-in-code-in-tools

Comment 45

[Elio Maldonado]

(In reply to Elio Maldonado from comment #40)
I don't think I stated my comment clearly. I actually favor checking in the patch because I think it will go a long way towards easing the the review process. In fact, I favor moving the man pages review from fedora to here. We would get the collaboration of aditional and well qualified reviwers. Having this patch makes it easier for reviwers an others to pick execute 'make all' and actually see genrate the results themselves. My concerns about having unnaproved xml test as part of the patch can be addressed by adding to it some a caveat such as "This is intended to facilate the review process of propossed man pages and as such it contains work in progress". By all means, I favor checking the patch in.

Comment 46

[Elio Maldonado]

Comment on attachment 708107 [details] [diff] [review]
Patch - add the existing docbook manpages to NSS CVS

r+, Consider adding a caveat such as the one suggested in Comment 45.

Comment 47

[Kai Engert (:KaiE:)]

Thanks for the review. I added a comment with a link to all documents as requested. I used the following text:

STATUS
This documentation is still work in progress. Please contribute to the initial review in Mozilla NSS bug 836477


RCS file: /cvsroot/mozilla/security/nss/doc/Makefile,v
done
Checking in Makefile;
/cvsroot/mozilla/security/nss/doc/Makefile,v  <--  Makefile
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/security/nss/doc/README,v
done
Checking in README;
/cvsroot/mozilla/security/nss/doc/README,v  <--  README
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/security/nss/doc/certutil.xml,v
done
Checking in certutil.xml;
/cvsroot/mozilla/security/nss/doc/certutil.xml,v  <--  certutil.xml
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/security/nss/doc/cmsutil.xml,v
done
Checking in cmsutil.xml;
/cvsroot/mozilla/security/nss/doc/cmsutil.xml,v  <--  cmsutil.xml
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/security/nss/doc/crlutil.xml,v
done
Checking in crlutil.xml;
/cvsroot/mozilla/security/nss/doc/crlutil.xml,v  <--  crlutil.xml
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/security/nss/doc/derdump.xml,v
done
Checking in derdump.xml;
/cvsroot/mozilla/security/nss/doc/derdump.xml,v  <--  derdump.xml
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/security/nss/doc/modutil.xml,v
done
Checking in modutil.xml;
/cvsroot/mozilla/security/nss/doc/modutil.xml,v  <--  modutil.xml
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/security/nss/doc/pk12util.xml,v
done
Checking in pk12util.xml;
/cvsroot/mozilla/security/nss/doc/pk12util.xml,v  <--  pk12util.xml
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/security/nss/doc/pp.xml,v
done
Checking in pp.xml;
/cvsroot/mozilla/security/nss/doc/pp.xml,v  <--  pp.xml
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/security/nss/doc/signtool.xml,v
done
Checking in signtool.xml;
/cvsroot/mozilla/security/nss/doc/signtool.xml,v  <--  signtool.xml
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/security/nss/doc/signver.xml,v
done
Checking in signver.xml;
/cvsroot/mozilla/security/nss/doc/signver.xml,v  <--  signver.xml
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/security/nss/doc/ssltap.xml,v
done
Checking in ssltap.xml;
/cvsroot/mozilla/security/nss/doc/ssltap.xml,v  <--  ssltap.xml
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/security/nss/doc/vfychain.xml,v
done
Checking in vfychain.xml;
/cvsroot/mozilla/security/nss/doc/vfychain.xml,v  <--  vfychain.xml
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/security/nss/doc/vfyserv.xml,v
done
Checking in vfyserv.xml;
/cvsroot/mozilla/security/nss/doc/vfyserv.xml,v  <--  vfyserv.xml
initial revision: 1.1
done

Comment 48

[Paul Wouters]

I find the argument non-coders must remain able to write documentation amusing, as the only documentation up to date seems to be the code. Furthermore, editing xml isn't _that_ hard.

Arguing against man pages because they would not be maintained indefinately, is saying that no docs are better than partial docs. I don't agree with that.

In response to Kai, for openswan/libreswan, we use xml as the source, but also commit the generated man pages to the source tree. Make will regenerate the man page if the xml gets updated. But developers then commit the updated generated man page. This allows people to cross compile the software without ending up cross compiling latex just to generate a man page. We also leave out any buildrequires for latex in the spec file on purpose.