Convertion to markdown from docbook

[coliss86]

Here is a first attempt to convert the documentation from docbook to markdown.

I'm using pandoc to automate the process but a thin review of each file producted is necessary to correct them. Moreover, the docbook file has to be modified to add the doctype declaration in order to help pandoc recognize the file.

For the memory, here the command I'm using

pandoc -f docbook -t markdown --verbose configuration.docbook -o configuration.md

I also keep the line breaks as they are but I think the source file is less readable.

[haraldg]

Thanks for looking into this. The result looks pretty good to me. Was thre any manual editing involved?

Since there is also issue #3 for this and @willfe owns that issue I'm waiting for his input.

[coliss86]

Yes, there were some manual editing to add some extra ``` and adjust indentation were applicable.

[coliss86]

any update about this ?

[haraldg]

@willfe ping

[willfe]

Crud, sorry. Life's been busy these past few months :(

On a brief glance it seems good to me. Feel free to merge if you're comfortable doing so, @haraldg.

[haraldg]

I don't think this is just about merging. Since the proposed conversion from docbook to markdown involves manual work, we sure won't maintain both versions. So I thnik there really is a decision to take here. I have no strong opinion about it, though.

I think it is a bug that we don't have an uptodate version of our documentation online and I guess having the documentation as markdown in git would help as presumeable this would make it browsable in github. However I don't intend to work on the website myself so I don't want to interfere with whoever picks up the duty.

[coliss86]

@haraldg any news on this subject ?
I'm proposing to migrate the docbook documentation to markdown. There will be a transition period where both format would exist, but the doc isn't moving for now, so I don't think it will be an issue.

[haraldg]

@coliss86 I still don't feel like the right person to decide on this. (And I'm not in contact with anybody behind the since, so I don't know anything then what is written in this thread.)

[willfe]

I don't think it's a bad idea to convert to markdown. It's easier to manage for sure, especially compared to docbook.

I really need to get the website updated too... sigh

[hsiboy]

ping @willfe is this merge good to go?