Comment 1 Ferenc Szekely 2007-05-07 00:58:31 UTC

IMO this bug belongs to the 'documentation' product. Beside that the
'documentation' product should be owned by Quim. CC:ing Jake as well.

Comment 2 Quim Gil 2007-05-07 10:46:53 UTC

Let's first decide who is responsible of solving this bug.  :)

The source HTML seems to be correct (I'm not the best person to assess code
consistency). What creates the trouble is the Midgard interpretation of that
source.

It looks that we need to go manually through the source HTML and tag as <pre>
all the code shown there. Or if we go semantix and XTML compliant we should use
<code>, and through CSS look the code look as code. We will be shipping a big
amount of code in our online documentation, so the use of the <code> tag might
be worth considering.

Proposal:

- Let's agree first on the policy: <code> yes or not.

- Then let's agree on the procedure: looks to me that each document owner
should review his docs, fixs what is/looks wrong and apply the policy.

- The CSS should be updated accordingly.

- Perhaps Midgard should add the "Code" option in their menu dropdown for text
styles.

PS: About documentation itself, my opinion is that it shouldn't be a product
standing alone. Instead, each product should have a documentation component. To
be discussed out of this bug.

Comment 3 Quim Gil 2007-05-07 10:47:59 UTC

Adding Ferenc since there are some CMS considerations. I though commenters were
automatically added to CC.

Comment 4 Quim Gil 2007-05-09 18:00:23 UTC

Oskari, this is a good example of code example not being well digested by
Midgard. Reassigning to you with the hope that we can find a general solution
to all the maemo pages with damaged code examples.

Comment 5 Quim Gil 2007-05-15 22:28:43 UTC

Hi Mika, please discuss here your ideas with Oskari, since he is in charge of
implementing this solution. Pick the phone if needed, skip myself since I'm not
critical here. This is urgent and we need the best solution possible.

Comment 6 Mika Luostarinen 2007-05-16 12:14:35 UTC

The script that did the conversion from the original XML docs (-> to midgard)
must be fixed and then rerun for all maemo docs. This is the fastest way to fix
the code snippets.


Note, that the source html is _not_ correct (for code snippets) because the
conversion script has removed parts of the original text.

Comment 7 Ferenc Szekely 2007-05-16 16:24:35 UTC

i am testing now the new script. stay tuned.

Comment 8 Quim Gil 2007-05-19 23:29:53 UTC

*** Bug 1377 has been marked as a duplicate of this bug. ***

Comment 9 Quim Gil 2007-05-19 23:30:51 UTC

*** Bug 1315 has been marked as a duplicate of this bug. ***

Comment 10 Quim Gil 2007-05-19 23:36:09 UTC

*** Bug 1348 has been marked as a duplicate of this bug. ***

Comment 11 Quim Gil 2007-05-19 23:38:51 UTC

Ok, if Ferenc is in charge then reassigning this bug to Ferenc.

Also increasing severity to critical, since the maemo tutorials are key
documents and in fact the solution of this bug affects most of our
documentation.

Comment 12 Ferenc Szekely 2007-05-21 21:51:48 UTC

the xml importer does not process the xml docs line by line, hence implementing
states there is problematic. why am i saying all this? the problem in question
occurs when we replace <source> elements with anything else. inside the
<source> we have various #include <'blabla'> definitions and these are of
course not valid HTML elements so the browser does not render them. solving the
include lines are theoretically easy (just replace < with &lt; and and > with
&gt;), but the script  needs to know whether we are in a <source> element or
not. 
the same stands for other samples, where we have xml sources, that are again
not valid HTML elements (ie. the browser will not render). i am still working
on the problem, hope some clever regexp will do the tricks...
cc-ing Henri just in case he has some good tips.

Comment 13 Mika Luostarinen 2007-05-22 09:39:37 UTC

Henri:
---
... inside the
<source> we have various #include <"blabla"> definitions and these are of
course not valid HTML elements so the browser does not render them. solving the
include lines are theoretically easy (just replace < with &lt; and and > with
&gt;), but the script  needs to know whether we are in a <source> element or
not. the same stands for other samples, where we have xml sources, that are
again
not valid HTML elements (ie. the browser will not render).
---

The thing is that the converter has REMOVED content that was in place in the
original XML file (at least that is what you see when you view the doc HTML
source in the browser). 

When we have a statements like #include <stdio.h> then the <stdio.h> part is
REMOVED because of a bug in the converter. The problem is not in the browser,
its in the XML converter that converts the original XML files to HTML files.
Please fix the converter.

There might also be another way to do that if fixing the converter is such a
difficult task (?): take the document pages that are already converted to HTML
format from the old test.maemo.org site, like this:

http://test.maemo.org/platform/docs/howtos/Maemo_tutorial_bora.html

and do the import to midgard using those ready HTML files.

Comment 14 Ferenc Szekely 2007-05-22 18:21:22 UTC

The XML importer was fixed and the re-import was done. Now the team reviews the
docs and publishes them (hopefully). My part is done, i guess. Marking it
fixed.

Comment 15 Quim Gil 2007-05-23 07:54:27 UTC

Reopening. We can't mark bugs as fixed until they are really fixed and tested. 

The URL above still shows code snippets damaged, hence the bug is still there.
Perhaps Ferenc has completed his part, but this doesn't mean the bug itself is
closed. If you have done your part but the fix is not completed you should
simply reassign to the right person.

Thanks

Comment 16 Ferenc Szekely 2007-05-23 09:52:51 UTC

First of all: since I was assigned to the bug, please let me decide when it is
fixed.

Secondly: sure the maemo.org doc is broken, but I asked you to review the
internal version. Did you read my mail?

Comment 17 Quim Gil 2007-05-23 11:39:02 UTC

There are some common bug tracking principles we all need to respect, no matter
who owns the bug. "Code snippets in tutorial are damaged" is not fixed
according to the most elemental quality checks. There is really nothing to
discuss here.

Reopening and reassigning it to Mika, since he is the owner at least of the
Bora tutorial (even if it's clear that he is not the responsible of all the
documents to be reviewed and re-published, that's clear).

At least you don't have this critical bug in your account, if this was the
reason behind this weird discussion we are having.

Comment 18 Ferenc Szekely 2007-05-23 13:47:26 UTC

No, again: the bug is fixed. This is the reason why I marked fix. Thanks for
the bugzilla lesson anyway. Check and review the docs on internal.maemo.org.

Comment 19 Niels Breet 2007-05-24 12:31:02 UTC

The only problem that still exists here is that the code example at
http://maemo.org/development/documentation/tutorials/Maemo_tutorial_bora.html#Quick-Start
has 4 or 5 tabs before each line. As we are using pre formatted text, these
tabs are visible. 

I can fix the flowing outside of the page with a few lines of CSS (just let me
know), but that still leaves the 4 tabs in front of the code. Maybe it is wise
to remove some of them in the original document first?

(In reply to comment #19)
> The only problem that still exists here is that the code example at
> http://maemo.org/development/documentation/tutorials/Maemo_tutorial_bora.html#Quick-Start
> has 4 or 5 tabs before each line. As we are using pre formatted text, these
> tabs are visible. 

Well, that's not the only problem. For example, look at
http://maemo.org/development/documentation/tutorials/Maemo_tutorial_bora.html#Application-Framework-environment

hello,

this bug affects multiple development documents on maemo.org which is kinda
critical:

http://maemo.org/development/documentation/how-tos/3-x/howto_help_framework_bora.html
http://maemo.org/development/documentation/how-tos/3-x/howto_him_bora.html
http://maemo.org/development/documentation/how-tos/3-x/howto_new_application_bora.html
http://maemo.org/development/documentation/how-tos/3-x/tutorial_desktop_plugins_bora.html
http://maemo.org/development/documentation/how-tos/3-x/howto_connection_managers_bora.html
http://maemo.org/development/documentation/how-tos/3-x/howto_porting_to_maemo_bora.html

etc...

Fixed by Mika.

Closing RESOLVED and FIX bugs. If error/problem still occurs, please reopen bug
with proper comments.