Convert the NetBSD Guide from DocBook to Markdown The NetBSD Project
Status: Closed Time to complete: 168 hrs Mentors: Iain Hibbert, Julian Coleman, Julian Fagir Tags: wiki

There are already tools to convert docbook to markdown (e.g. pandoc), so they have to be applied. The results have to be checked whether they are useful, and then every chapter should be a single wiki article, with one overview, such that the user optimally doesn't see the difference between the website and the wiki guide.

The guide: http://www.netbsd.org/docs/guide/en/index.html

The sources: http://cvsweb.netbsd.org/bsdweb.cgi/htdocs/docs/guide/

Uploaded Work
File name/URL File size Date submitted
markdown.zip 296.6 KB November 28 2012 08:35 UTC
md_no_toc.zip 292.2 KB December 02 2012 03:34 UTC
Comments
wmzhere on November 28 2012 00:33 UTC Task Claimed

I would like to work on this task.

wmzhere on November 28 2012 02:29 UTC Submitting Help

Hello everyone.


I have finished this task. How could I upload my results? I found no "Upload" or "Submit" button here and I just want to move to another task. Now I'm locked here and can't claim other tasks.


Can someone help? Thanks.

Aleksej Saushev on November 28 2012 08:20 UTC Uploading

Either upload it using Melange interface or send it to one of mentors.


 

Aleksej Saushev on November 28 2012 08:27 UTC Task Assigned

This task has been assigned to wmzhere. You have 168 hours to complete this task, good luck!

wmzhere on November 28 2012 08:35 UTC Ready for review

The work on this task is ready to be reviewed.

wmzhere on November 28 2012 08:37 UTC Tips

Use 00build.sh to compile all markdowns to htmls for reviewing. Use 00del.sh to delete all built htmls.

Iain Hibbert on November 28 2012 09:25 UTC needs more work

Hi


I don't have time to fully review this at the moment (and will be offline today), but I think it may need more work. There are non-ascii characters in the source (eg quotes, chapter numbering) at least


Also, I am not sure about having the chapter numbering within the markdown, since everything must be renumbered when chapters are inserted. Is there a way to produce those automatically, as was done with the xml->html translation?


Finally as we are unable to offer write access to the official netbsd wiki at this time, we have set up a separate wiki for use by Google Code-In students; please see


    http://komkon2.de/nbwiki/doku.php?id=start


for details

Iain Hibbert on November 28 2012 09:26 UTC Task Needs More Work

One of the mentors has sent this task back for more work. Talk to the mentor(s) assigned to this task to satisfy the requirements needed to complete this task, submit your work again and mark the task as complete once you re-submit your work.

Julian Fagir on November 28 2012 11:43 UTC Chapter numbers

Hi,


I also think chapter numbers should not be included. They will be inserted with the conversion to latex or whatever.


For the wiki, in short: We need an e-mail address and a username from you to create an account. Then you can insert the chapters in the wiki, where you can also provide working links between the documents.


Regards, Julian 

wmzhere on November 28 2012 12:44 UTC non-ascii characters

Thanks for your advice. However, I checked my files and found there are no non-ascii characters. Did you mean that HTML tags should be stripped?

wmzhere on November 28 2012 12:59 UTC Wiki Account

Thanks for your description of wiki.


I asked for an account by IRC but I got no response. Would you please email an account to me?

wmzhere on November 28 2012 13:13 UTC RE: Chapter numbers

Hi, 


When checking the output carefully, I found that the chaper numbers are referenced in the main content.


For example, (ap-ack.html)


Hubert Feyrer, who contributed the Introduction to TCP/IP Networking in Chapter 23, Introduction to TCP/IP Networking including Next generation Internet protocol - IPv6 and the section on getting IPv6 Connectivity & Transition via 6to4 in Section 24.9, “IPv6 Connectivity & Transition via 6to4”. He also helped with the SGML to XML transition.


So simply removing the numbers or using markdown to auto increase the numbers are not the best solution.


It's obvious that Markdown can not provide cross-document referencing. But how can we make it better?

Julian Fagir on November 28 2012 15:00 UTC Wiki account, chapter numbering, non-ascii characters

Hi,


for the wiki account: I didn't read your request. Please either wait longer, ask again or just post your supposed username and e-mail address here and we will add an account for you.


For the chapter numbering: If it is referenced, this doesn't matter. Do you know if there are many references? If so, maybe just remove them or replace them by links.


For references, you can just use links. You can simply add them when you have the wiki account. The wiki has a syntax where it uses [[page|description]] for wiki-internal links. You would e.g. reference chap-build.markdown with [[chap-build|Chapter about building]] or so.


For non-ascii characters: There is e.g. the file chap-build.markdown, in line 488, you have:


488 ChapterÂ| 30.Â| Obtaining the sourcesÂ|


If you look at it with a non-UTF and non-latin editor. 


Regards, Julian 

wmzhere on November 29 2012 06:15 UTC ikiwiki and internal links

Hi, 


Dokuwiki gives each title an anchor. Such as 


http://komkon2.de/nbwiki/doku.php?id=start#changes_in_the_wiki_itself


<h3 class="sectionedit4" id="changes_in_the_syntax">Changes in the syntax</h3>


However, when I cheked it in ikiwiki, I found that the name of the anchors were strange . The support of anchors is poor in ikiwiki. I also searched for the detail in ikiwiki's official site but found nothing. The only way is to use inline HTML. And that makes markdown much more difficult to read.


How should we configure ikiwiki to support anchors? Or I should just ignore internal links and just link to one page itselt? I'm trying to ignore anchors.

Iain Hibbert on November 29 2012 10:40 UTC chapter numbers

with regards to chapter numbering, this is not present in the original docbook XML source which was used to generate the HTML output.. if you examine the ap-ack.xml file, you will see that it contains


      <listitem>
<para>Hubert Feyrer, who contributed the Introduction to TCP/IP
Networking in <xref linkend="chap-net-intro" /> including Next
generation Internet protocol - IPv6 and the section on
getting IPv6 Connectivity &amp; Transition via 6to4 in <xref
linkend="chap-net-practice-ipv6-6to4" />. He also helped with the
SGML to XML transition.</para>
</listitem>

so the chapter reference is cross referenced by name, and during the docbook build process this
is calculated and inserted into the HTML document.

the Markdown source should reflect this; I guess that in the wiki/html environment, the cross reference
should result in a link to the other document (or page) but we do want to be able to produce a
standalone document suitable for including in a release (either plain ascii text, or pdf) which can
be printed, and this should have chapter headers so that cross references can be followed by a human.
That second part is outside the scope of this task though, so I think that direct anchor links are acceptable

Iain Hibbert on November 29 2012 10:56 UTC docuwiki vs ikiwiki

regarding this, I think for the purposes of Google Code-In, we should accept the result that works on Docuwiki, since that is what you have write access for. The NetBSD wiki-site is still technically under construction and perhaps it will need to have something like the headinganchors plugin added, if required.

wmzhere on November 29 2012 11:59 UTC Bug of asterisk

Hi,


Dokuwiki can not parse "*nix" to "*nix". It changes the following text's style.


Using the official Markdown.pl (from daringfireball), it outputs the original text.


I have problem escaping asterisk. Please help me.


Thank you.

wmzhere on November 29 2012 12:38 UTC Markdown error

Hi, 


BTW, the first line under <code> tag can not be recognized correctly.  Other markdown processors works fine.

Julian Fagir on November 29 2012 13:08 UTC Re: Bug of asterisk

Hi,


sorry, there was an error in the regexp parsing the asterisk. It should work now. 


Regards, Julian 

Julian Fagir on November 29 2012 13:11 UTC Re: Markdown error

Hi,


I cannot reproduce what you meant. Could you please hint me to an example page?


Btw: I know there are errors in this markdown plugin. You don't have to care for them if the dokuwiki does not show your markup correctly. Just ignore it, we will do so as well. Please just report them.


Regards, Julian 

wmzhere on November 29 2012 13:18 UTC Bug report

Hi, 


Thanks for your work. Now it seems works correctly.


And here's the example for line break recognizing bug.


URL:


http://komkon2.de/nbwiki/doku.php?id=guide:installing_netbsd:preliminary_considerations_and_preparations&do=edit&rev=0


Source:


To create a boot floppy in a Unix environment, the `dd` command can be used: For example:


 


    RPROMPT 


          RPROMPT


 


 


 


 


> **Note**


>


> A 1440K floppy contains 1474560 bytes and is made up of 80 cylinders, 2 tracks, 18 sectors and 512 bytes per sector, i.e., 80 * 2 * 18 = 2880 blocks. Thus bs=36b copies one cylinder (18 * 2 blocks) at a time and repeats the operation 80 times instead of 2880.


Output:


 


 


Note




A 1440K floppy contains 1474560 bytes and is made up of 80 cylinders, 2 tracks, 18 sectors and 512 bytes per sector, i.e., 80 * 2 * 18 = 2880 blocks. Thus bs=36b copies one cylinder (18 * 2 blocks) at a time and repeats the operation 80 times instead of 2880.


 

wmzhere on December 2 2012 03:34 UTC Ready for review

The work on this task is ready to be reviewed.

wmzhere on December 2 2012 03:51 UTC Bug Report of markdown plugin of DokuWiki

It's the first time that I wirte a bug report. Please tell me if there are problems of this bug report.


 


Organization:


markdown plugin of Dokuwiki


Environment:


http://komkon2.de/nbwiki/doku.php?id=md_plugin_bugs


Description:


Links in title are not converted to links. Original text is output.


How-To-Repeat:


Create a link and add "#" to the beginning of the line. Then see the result.


Minimal Testcase:


 # [Links in title](http://www.example.com)

Julian Fagir on December 2 2012 20:48 UTC Some minor work required, thank you for the bug reports

Thank you for reporting the bugs. The report format is nice. I will fix this soon.


There are still UTF-8 characters in your code, but I see they're also in the HTML files of the guide. If you want, you can still just convert them or insert the articles into the wiki. I think they're mainly the "-characters which are the "right" ones (for the beginning and ending).


Anyway, this bug will be closed now. Thank you very much for your work!

Julian Fagir on December 2 2012 20:48 UTC Task Closed

Congratulations, this task has been completed successfully.

Julian Fagir on December 2 2012 20:49 UTC The task will be closed now

Ehrm, I mean the task will be closed now.

wmzhere on December 3 2012 01:54 UTC Further improvement and a suggestion about the official docbook

Hi, 


Although the task is closed, I want to encode the UTF-8 characters so that the text can be saved in ASCII encoding. However, I see no "Upload" buttons here because this task has been marked as "Closed".


How can I hand in my work?


Thank you.




PS:


In the original docbook, "NetBSD" and "&os;" are both used. So I think maybe we should replace "&os;" to "NetBSD" or replace "NetBSD" to "&os;". They should be in one form.

Julian Fagir on December 3 2012 15:57 UTC Upload in the wiki

Thank you very much for having interest in the project though the task is already done. This task cannot be reopened anyway, it is already closed.


You can just upload the new tasks to a wiki page. Just e.g. create your own page and then append it to that page.


And concerning the "&os" vs. "NetBSD" question, I think the "&os" can be replaced by "NetBSD". There is no need for a generic OS tag, the guide will be used for NetBSD only anyway.