Open Bug 350643 (bz-pod) Opened 18 years ago Updated 18 years ago

Our POD should render better (it looks bad, currently)

Categories

(Bugzilla :: Bugzilla-General, enhancement)

Product:
Bugzilla
Component:
Bugzilla-General
Version:
2.23
Type:
enhancement
Priority:
Not set
Severity:
normal

Tracking

()

People

(Reporter: mkanat, Unassigned)

References

Details

When the POD for our modules is rendered, with the "Description/Params/Returns" format, it doesn't look good, because of how we're formatting the POD. Instead, I've found that this looks good (example from Bugzilla::DB): ----------------------------------- =head3 C<bz_check_requirements> =over =item B<Description> Checks to make sure that you have the correct DBD and database version installed for the database that Bugzilla will be using. Prints a message and exits if you don't pass the requirements. If C<$db_check> is false (from F<localconfig>), we won't check the database version. =item B<Params> =over =item C<$output> - C<true> if the function should display informational output about what it's doing, such as versions found. =back =item B<Returns> (nothing) =back -------------------------------------------- Notice a few things: * Instead of =items, the functions are =head3. * The actual =head3 item itself never has the parameters specified. This lets us link to this doc from other PODs. * The Param section is specified as a list of =items. * Description, Params, and Returns are in bold. This looks much better than the raw text block that we were rendering before. It also allows us to be much more flexible with our POD. To fix all our POD would be a huge project, so this is more of a meta-bug than anything else, to track the effort to make our POD render better.
Okay, it actually works even better if you keep the =head3 as an =item. It indents the whole doc for the individual function and makes it much easier to browse through the POD quickly.
Alias: bz-pod
Depends on: 350649
So this leaves us with "Description, Params, and Returns are in bold"? I don't think it's a good idea to tamper with rendering when writing docs. This is the job of either the POD parser/HTML-generator or of some CSS we supply with it (ActiveState perl docs are a good example imo).
I don't care too much about POD, as long as information is there in a readable way. I hope we are not going to r- patches because POD is not written in the exact way a reviewer wants it to be, for the exact reason Marc mentioned above, i.e. there will probably be no consensus among reviewers about how POD should look like.
Given that HTML is the main target for our POD, we should write POD which produces the most semantic HTML, and then style it with CSS. Does the current POD structure we use produce good semantics? Or not? Gerv
(In reply to comment #2) > I don't think it's a good idea to tamper with rendering when writing docs. I agree completely, except POD is very limited. It's not HTML, and it doesn't have the same semantics as HTML. It's not even javadoc, which is actually designed for documenting functions. (In reply to comment #3) > I don't care too much about POD, as long as information is there in a readable > way. That's the problem--in many cases, it's not readable. It may be readable in the code, but once it's easily accessible in HTML, it's not readable. At least the text format can be somewhat readable, but the HTML is often very strange looking and not readable. I don't plan on r-'ing patches for POD rending nits, but I would like to get some standardization on how we write it, and make it easy to write. (In reply to comment #4) > Does the current POD structure we use produce good semantics? Or not? No, the current POD structure we use produces either a <pre> block or a single paragraph with no line breaks in it. Or paragraphs followed by arbitrary <pre> blocks. Take a look at the sample in bug 350649--that's how what I've proposed renders. I spent many, many hours last night trying to find a way that makes sense both in semantic HTML and in POD, and the recommendations above are what I came up with. It's possible that =head3 makes more semantic sense for the names of functions, and =head4 makes more semantic sense for Description/Returns/Params, but unfortunately they don't produce an easily style-able block below them. That is, a =head3 renders into an <h3>. That's great, that makes total sense. The problem is that then I want to do something with the whole block under the <h3>, until the next =head3 statement, and I can't do that, because the POD parser doesn't render things that way. Also, you can't put =head statements inside of =over blocks in POD, so that prevents us from using =head for Description/Returns/Params and =item for the functions, which would be ideal. What I've proposed *does* in fact generate semantic HTML that makes sense. It produces definition lists inside definition lists, which definitely makes the most sense for documenting things in POD. The only reason that Description/Returns/Params is explicitly bold is because POD doesn't have any idea of things like CSS classes. Description/Returns/Params are all going to be <dt> elements, but I can't guarantee at what level in the list of lists they'll be, and I can't style all <dt> elements bold because that would affect the params list and any other =item list in the POD. So that's the only exception. Othewise it entirely makes sense, semantically.
(In reply to comment #5) > most sense for documenting things in POD. The only reason that > Description/Returns/Params is explicitly bold is because POD doesn't have any > idea of things like CSS classes. Description/Returns/Params are all going to be Well we can use CSS to render all h3 (or whatever) in bold, can't we? Why specify it explicitly in POD?
(In reply to comment #6) > Well we can use CSS to render all h3 (or whatever) in bold, can't we? Why > specify it explicitly in POD? They're *not* h3, right now. They're <dt>. Just like every other =item in all of our POD. I described the problems with <h3> above. We could do it, but it wouldn't produce POD as readable as what I've proposed. Unless we remembered to do an =over under every =head3, and an =over under every =head4, just to get the correct indentation. Also, the =head3/=head4 solution can only be made to look nice in Gecko, because it requires the use of the "+" CSS selector, for items that immediately follow an h3 or h4. Otherwise there's far too much whitespace in the generated HTML. I actually agree that *semantically*, =head3 and =head4 are better solutions. (They also require that functions ALWAYS be =head3, and never =head2, meaning that they always have to have a =head2 above them.) But the =item solution renders much better, is much easier to write, and is less error-prone. The primary problem is that POD does not allow you to have =head4 inside of an =over block. So even though we could have an <h4> inside of a <blockquote> inside of the HTML, podchecker would throw an error for that condition, because it's specifically disallowed by the POD Specification. Making Description/Returns/Params bold is a compromise that I made in order to have a nice-looking and easy-to-read/scan rendering result.
There seem to be a stupid number of Perl modules which convert POD to HTML: http://search.cpan.org/search?m=all&q=POD+html&s=21 Surely one of them will do a better job than the default? I don't think it would be unreasonable to require it. We require plenty of modules already :-) Gerv
(In reply to comment #8) > Surely one of them will do a better job than the default? I don't think it > would be unreasonable to require it. We require plenty of modules already :-) I am using something other than the default. In fact, I'm using the quite-nice Pod::Simple::HTML, with my own subclass of it called Pod::Simple::HTML::Bugzilla. Its rendering is very nice, and is not generally at fault. It does exactly what I expect it to do. (In reply to comment #9) > See also the amusing: > http://obsidianrook.com/devnotes/pod-html-summary.html Yes, I spent many hours yesterday looking through various Pod-to-HTML solutions, and I also came up with the same solution he did, which was Pod::Simple::HTMLBatch. That's what I'm using.
Then I'm confused by this question and answer: > > Does the current POD structure we use produce good > > semantics? Or not? > > No, the current POD structure we use produces either a > <pre> block or a single paragraph with no line breaks in > it. Or paragraphs followed by arbitrary <pre> blocks. If what we are using now generates semantic HTML (<hX> for headings, <p> for paragraphs, nice classes for identifiers, etc. etc.) then let's use that and style it. If it doesn't, let's hack your module until it does. Unless you are suggesting that the current POD structure is such that it's impossible to produce good semantic HTML from it without mind-reading? Gerv
(In reply to comment #11) > Unless you are > suggesting that the current POD structure is such that it's impossible to > produce good semantic HTML from it without mind-reading? The current POD structure is actually an *instruction* to the POD parser to produce pre-formatted blocks of code (<pre> blocks). I read the perlpod man page the other day for the first time, and it made me understand a lot of things. It's actually not that hard to read, and I should have done it a while ago. Basically, any paragraph that starts with a space is considered to be pre-formatted text. So, we have to fix what we have to actually be sensible POD, not just so that it renders correctly. We have to tell the POD that our list of params is a list, not preformatted text. Unfortunately, the world of POD rendering is not a nice and happy world. :-) I've spent quite a bit of time in it lately. It would make more sense if our POD were just written directly in HTML than it does as POD, but from POD it's easier to generate multiple formats than it is from direct HTML, so... Trust me, I'm a huge champion of semantic HTML. That's one of the reasons I'm proposing this change to our POD structure, actually--so that it's *possible* to produce some semantic HTML. Just look at the current rendered form of Bugzilla::DB (which I've fixed to have the format suggested above) versus, say, the rendered form of Bugzilla::DB::Schema: DB: http://landfill.bugzilla.org/mkanat/docs/api/Bugzilla/DB.html DB::Schema: http://landfill.bugzilla.org/mkanat/docs/api/Bugzilla/DB/Schema.html That can't be changed without modifying the POD itself. Also, even the text format of that POD can look terrible. It frequently takes up more than 80 characters on the screen...it's just bad POD. We wrote it in a fashion that was a mistake, and now we need to fix it.
I certainly agree the look is an improvement, and the HTML is slightly better. But I still don't think it's all that semantic. While you could argue that bz_add_index is a definition term and all the data is a definition definition (!), it's not really true that "Params" is a <dt> and the info about the params is a <dd>. I'd much prefer an <h3> or <h4> followed by a <p>. (Also, as a nit, you have loads of <a name="foo"> anchors with the same value of foo. That's not good.) Having said that, do you plan to write a stylesheet to show it off? Gerv
(In reply to comment #13) > (Also, as a nit, you have loads of <a name="foo"> anchors with the same value > of foo. That's not good.) I know. I can't control that--that's how POD works with anchors. > Having said that, do you plan to write a stylesheet to show it off? It does have a stylesheet. The URLs have moved, and I'm editing the code, so you might have seen it unstyled briefly: http://landfill.bugzilla.org/mkanat/docs/html/api/Bugzilla/DB.html
Depends on: 350613
Ah! Indeed; that looks much smarter. I approve :-) Gerv
You need to log in before you can comment on or make changes to this bug.