JBD Documentation added in BK-current

JBD Documentation added in BK-current

[Sam Ravnborg]

The JBD documentation have been added in BK-current.
But 'compiling' the documentation result in a lot of SGML related
errors.

Someone knowing SGML that care to take a look?

[I'm cleaning up the mess in the Makefile after JBD was added right now].

	Sam

  DB2PS   Documentation/DocBook/journal-api.ps
Using catalogs: /etc/sgml/sgml-docbook-3.1.cat
Using stylesheet: /usr/share/sgml/docbook/utils-0.6.9/docbook-utils.dsl#print
Working on: /home/sam/src/linux/kernel/bk/clean3/Documentation/DocBook/journal-api.sgml
jade:/home/sam/src/linux/kernel/bk/clean3/Documentation/DocBook/journal-api.sgml:211:5:E: document type does not allow element "PARA" here; missing one of "FOOTNOTE", "MSGTEXT", "CAUTION", "IMPORTANT", "NOTE", "TIP", "WARNING", "BLOCKQUOTE", "INFORMALEXAMPLE" start-tag
jade:/home/sam/src/linux/kernel/bk/clean3/Documentation/DocBook/journal-api.sgml:212:7:E: end tag for "PARA" omitted, but OMITTAG NO was specified
jade:/home/sam/src/linux/kernel/bk/clean3/Documentation/DocBook/journal-api.sgml:211:0: start tag was here
jade:/home/sam/src/linux/kernel/bk/clean3/Documentation/DocBook/journal-api.sgml:212:7:E: end tag for "PARA" omitted, but OMITTAG NO was specified
jade:/home/sam/src/linux/kernel/bk/clean3/Documentation/DocBook/journal-api.sgml:195:0: start tag was here
jade:/home/sam/src/linux/kernel/bk/clean3/Documentation/DocBook/journal-api.sgml:248:9:E: end tag for "PARA" omitted, but OMITTAG NO was specified
jade:/home/sam/src/linux/kernel/bk/clean3/Documentation/DocBook/journal-api.sgml:215:0: start tag was here
jade:/home/sam/src/linux/kernel/bk/clean3/Documentation/DocBook/journal-api.sgml:248:9:E: end tag for "SECT1" omitted, but OMITTAG NO was specified
jade:/home/sam/src/linux/kernel/bk/clean3/Documentation/DocBook/journal-api.sgml:213:0: start tag was here

Re: JBD Documentation added in BK-current

[Roger Gammans]

[-- Attachment #1: Type: text/plain, Size: 2896 bytes --]

On Tue, Oct 08, 2002 at 09:23:10PM +0200, Sam Ravnborg wrote:
> The JBD documentation have been added in BK-current.
> But 'compiling' the documentation result in a lot of SGML related
> errors.
> 
> Someone knowing SGML that care to take a look?

Well. I'm not surprised there are a few I couldn't find an SGML reference
for the linuxdoc dtd , or a tutorial when I wrote it, so I guessed by looking
at other documents and source code. 

I thought I'd checked the warnings

> [I'm cleaning up the mess in the Makefile after JBD was added right now].

Did I really make it that messy?
I'm a little behind with bk pulling and it takes 2-3hours to do each pull
here, so I can't be sure until tomorrow .

but if the line number haven't changed...

>   DB2PS   Documentation/DocBook/journal-api.ps
> Using catalogs: /etc/sgml/sgml-docbook-3.1.cat
> Using stylesheet: /usr/share/sgml/docbook/utils-0.6.9/docbook-utils.dsl#print
> Working on: /home/sam/src/linux/kernel/bk/clean3/Documentation/DocBook/journal-api.sgml
> jade:/.../journal-api.sgml:211:5:E: document type does not allow element "PARA" here; missing one of "FOOTNOTE", "MSGTEXT", "CAUTION", "IMPORTANT", "NOTE", "TIP", "WARNING", "BLOCKQUOTE", "INFORMALEXAMPLE" start-tag
> jade:/.../journal-api.sgml:212:7:E: end tag for "PARA" omitted, but OMITTAG NO was specified
> jade:/.../journal-api.sgml:212:7:E: end tag for "PARA" omitted, but OMITTAG NO was specified

Oops, there are errant <para> tag journal-api.tmpl line 211. Delete the line.

> jade:/.../journal-api.sgml:248:9:E: end tag for "PARA" omitted, but OMITTAG NO was specified
> jade:/.../journal-api.sgml:248:9:E: end tag for "SECT1" omitted, but OMITTAG NO was specified

Hmm, can't see what these asre unless they are run-on errors form above.

Hang on. yup they seem to be.... , the trivial patch follows.

You also mentioned in private mail to me that you think there is
a requirement for BKL to be held on some journal calls. Could
someone else preferably part of the ext3 maintance team give me
cahpter and verse on this situationin 2.4 and 2.5 so I can
ensure the docs are correct, assuming they aren't already which is quite
likely since the docs were written by inspection of the ext3/jbd code 
and reading of various other docs avaliable (as mention in the sgml).


diff -Nru a/Documentation/DocBook/journal-api.tmpl b/Documentation/DocBook/journal-api.tmpl
--- a/Documentation/DocBook/journal-api.tmpl	Mon Oct 14 22:46:55 2002
+++ b/Documentation/DocBook/journal-api.tmpl	Mon Oct 14 22:46:55 2002
@@ -208,7 +208,6 @@
 if you allow unprivileged userspace to trigger codepaths containing these
 calls.
 
-<para>
 </sect1>
 <sect1>
 <title>Summary</title>


TTFN
-- 
Roger.
Master of Peng Shui.  (Ancient oriental art of Penguin Arranging)
GPG Key FPR: CFF1 F383 F854 4E6A 918D  5CFF A90D E73B 88DE 0B3E

[-- Attachment #2: Type: application/pgp-signature, Size: 232 bytes --]

Re: JBD Documentation added in BK-current

[Sam Ravnborg]

On Mon, Oct 14, 2002 at 11:03:15PM +0100, Roger Gammans wrote:
> 
> Well. I'm not surprised there are a few I couldn't find an SGML reference
> for the linuxdoc dtd , or a tutorial when I wrote it, so I guessed by looking
> at other documents and source code. 
> 
> > [I'm cleaning up the mess in the Makefile after JBD was added right now].
> 
> Did I really make it that messy?
The infrastructure in the docbook makefile has changed since 2.4.

Took a look in the journal-api.sgml file, based on the comments you gave.
I had to do a little more to crete .html without warnings.
I've submitted this to Linus and trivial.. as well.

Browsing the resulting file I wonder why there are references to several
jbd files, but they do not include docgen comments.
Are there some patches missing in 2.5 that updates the comments?

	Sam

===== Documentation/DocBook/journal-api.tmpl 1.1 vs edited =====
--- 1.1/Documentation/DocBook/journal-api.tmpl	Mon Oct  7 16:36:06 2002
+++ edited/Documentation/DocBook/journal-api.tmpl	Tue Oct 15 20:06:15 2002
@@ -208,7 +208,7 @@
 if you allow unprivileged userspace to trigger codepaths containing these
 calls.
 
-<para>
+</para>
 </sect1>
 <sect1>
 <title>Summary</title>
@@ -244,7 +244,8 @@
    }
    journal_destroy(my_jrnl);
 </programlisting>
-
+</para>
+</sect1>
 </chapter>
 
   <chapter id="adt">

Re: JBD Documentation added in BK-current

[Roger Gammans]

[-- Attachment #1: Type: text/plain, Size: 1849 bytes --]

On Tue, Oct 15, 2002 at 08:16:48PM +0200, Sam Ravnborg wrote:
> On Mon, Oct 14, 2002 at 11:03:15PM +0100, Roger Gammans wrote:
> > 
> > Well. I'm not surprised there are a few I couldn't find an SGML reference
> > for the linuxdoc dtd , or a tutorial when I wrote it, so I guessed by looking
> > at other documents and source code. 
> > 
> > > [I'm cleaning up the mess in the Makefile after JBD was added right now].
> > 
> > Did I really make it that messy?
> The infrastructure in the docbook makefile has changed since 2.4.
> 
> Took a look in the journal-api.sgml file, based on the comments you gave.
> I had to do a little more to crete .html without warnings.
> I've submitted this to Linus and trivial.. as well.
> 
> Browsing the resulting file I wonder why there are references to several
> jbd files, but they do not include docgen comments.
> Are there some patches missing in 2.5 that updates the comments?

And in 2.4 AFAICT. There is a lot of documentation in the those
c and h files if you look.

The original patch didn;t two thing at once ( bad I know) 
   1 ) split the internal algorithm and public api comments
   2 ) reformat the api comments for docgen.
   
This result in something like 40 extra ps/pdf pages of docs, two
things occur to that there may have been some conflict in the
the .c files when merge due to the time between diff and applying, also
it appears davej passed the file to linux so as small stuff so the docgen
changes prolly need to come throught the ext3 team rather than dave.

If the later is the case it'll prolly fix itself it the fullness as time
as the ext3 team are reviewing the docs.., arent they Andrew??

TTFN
-- 
Roger.
Master of Peng Shui.  (Ancient oriental art of Penguin Arranging)
GPG Key FPR: CFF1 F383 F854 4E6A 918D  5CFF A90D E73B 88DE 0B3E

[-- Attachment #2: Type: application/pgp-signature, Size: 232 bytes --]