From mboxrd@z Thu Jan 1 00:00:00 1970 From: Danilo Cesar Lemes de Paula Subject: Re: [PATCH] scripts/kernel-doc: Improve Markdown results Date: Tue, 1 Sep 2015 14:57:33 -0300 Message-ID: <55E5E70D.4050201@collabora.co.uk> References: <1440185942-31030-1-git-send-email-danilo.cesar@collabora.co.uk> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Return-path: In-Reply-To: <1440185942-31030-1-git-send-email-danilo.cesar@collabora.co.uk> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" Cc: Michal Marek , Herbert Xu , Jonathan Corbet , Stephan Mueller , Daniel Vetter , intel-gfx , Randy Dunlap , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, dri-devel , Graham Whaley , Laurent Pinchart List-Id: dri-devel@lists.freedesktop.org T24gMDgvMjEvMjAxNSAwNDozOSBQTSwgRGFuaWxvIENlc2FyIExlbWVzIGRlIFBhdWxhIHdyb3Rl Ogo+IFVzaW5nIHBhbmRvYyBhcyB0aGUgTWFya2Rvd24gZW5naW5lIGNhdXNlIHNvbWUgbWlub3Ig c2lkZSBlZmZlY3RzIGFzCj4gcGFuZG9jIGluY2x1ZGVzICBtYWluIDxwYXJhPiB0YWdzIGZvciBh bG1vc3QgZXZlcnl0aGluZy4KPiBPcmlnaW5hbCBNYXJrZG93biBzdXBwb3J0IGFwcHJvYWNoIHJl bW92ZXMgdGhvc2UgbWFpbiB0YWdzLCBidXQgaXQgY2F1c2VkCj4gc29tZSBpbmNvbnNpc3RlbmNp ZXMgd2hlbiB0aGF0IHRhZyBpcyBub3QgdGhlIG1haW4gb25lLCBsaWtlOgo+IDxzb21ldGhpbmc+ Li48L3NvbWV0aGluZz4KPiA8cGFyYT4uLi48L3BhcmE+Cj4gCj4gQXMga2VybmVsLWRvYyB3YXMg YWxyZWFkeSBpbmNsdWRpbmcgYSA8cGFyYT4gdGFnLCBpdCBjYXVzZXMgdGhlIHByZXNlbmNlCj4g b2YgZG91YmxlIDxwYXJhPiB0YWdzICg8cGFyYT48cGFyYT4pLCB3aGljaCBpcyBub3Qgc3VwcG9y dGVkIGJ5IERvY0Jvb2sKPiBzcGVjLgo+IAo+IEh0bWwgdGFyZ2V0IGdldHMgYXdheSB3aXRoIGl0 LCBzbyBpdCBjYXVzZXMgbm8gaGFybSwgYWx0aG91Z2ggb3RoZXIKPiB0YXJnZXRzIG1pZ2h0IG5v dCBiZSBzbyBsdWNreSAocGRmIGFzIGV4YW1wbGUpLgo+IAo+IFdlJ3JlIG5vdyBkZWxlZ2F0aW5n IHRoZSBpbmNsdXNpb24gb2YgdGhlIG1haW4gPHBhcmE+IHRhZyB0byBwYW5kb2MKPiBvbmx5LCBh cyBpdCBrbm93cyB3aGVuIGl0J3MgbmVjZXNzYXJ5IG9yIG5vdC4KPiAKPiBUaGF0IGJlaGF2aW9y IGNhdXNlcyBhIGNvcm5lciBjYXNlLCB0aGUgb25seSBzaXR1YXRpb24gd2hlcmUgd2UncmUKPiBj ZXJ0YWlubHkgdGhhdCA8cGFyYT4gaXMgbm90IG5lZWRlZCwgd2hpY2ggaXMgdGhlIDxyZWZwdXJw b3NlPiBjb250ZW50Lgo+IEZvciB0aG9zZSBjYXNlcywgd2UncmUgdXNpbmcgYSAkb3V0cHV0X21h cmtkb3duX25vcGFyYSA9IDEgY29udHJvbCB2YXIuCj4gCj4gU2lnbmVkLW9mZi1ieTogRGFuaWxv IENlc2FyIExlbWVzIGRlIFBhdWxhIDxkYW5pbG8uY2VzYXJAY29sbGFib3JhLmNvLnVrPgo+IENj OiBSYW5keSBEdW5sYXAgPHJkdW5sYXBAaW5mcmFkZWFkLm9yZz4KPiBDYzogRGFuaWVsIFZldHRl ciA8ZGFuaWVsLnZldHRlckBmZndsbC5jaD4KPiBDYzogTGF1cmVudCBQaW5jaGFydCA8bGF1cmVu dC5waW5jaGFydEBpZGVhc29uYm9hcmQuY29tPgo+IENjOiBKb25hdGhhbiBDb3JiZXQgPGNvcmJl dEBsd24ubmV0Pgo+IENjOiBIZXJiZXJ0IFh1IDxoZXJiZXJ0QGdvbmRvci5hcGFuYS5vcmcuYXU+ Cj4gQ2M6IFN0ZXBoYW4gTXVlbGxlciA8c211ZWxsZXJAY2hyb25veC5kZT4KPiBDYzogTWljaGFs IE1hcmVrIDxtbWFyZWtAc3VzZS5jej4KPiBDYzogbGludXgta2VybmVsQHZnZXIua2VybmVsLm9y Zwo+IENjOiBsaW51eC1kb2NAdmdlci5rZXJuZWwub3JnCj4gQ2M6IGludGVsLWdmeCA8aW50ZWwt Z2Z4QGxpc3RzLmZyZWVkZXNrdG9wLm9yZz4KPiBDYzogZHJpLWRldmVsIDxkcmktZGV2ZWxAbGlz dHMuZnJlZWRlc2t0b3Aub3JnPgo+IENjOiBHcmFoYW0gV2hhbGV5IDxncmFoYW0ud2hhbGV5QGxp bnV4LmludGVsLmNvbT4KPiAtLS0KPiAgVGhhbmtzIHRvIEdyYWhhbSBXaGFsZXkgd2hvIGhlbHBl ZCBtZSB0byBkZWJ1ZyB0aGlzLgo+IAo+ICBzY3JpcHRzL2tlcm5lbC1kb2MgfCA0OCArKysrKysr KysrKysrKysrKysrKysrKysrKysrKysrKysrLS0tLS0tLS0tLS0tLS0KPiAgMSBmaWxlIGNoYW5n ZWQsIDM0IGluc2VydGlvbnMoKyksIDE0IGRlbGV0aW9ucygtKQo+IAo+IGRpZmYgLS1naXQgYS9z Y3JpcHRzL2tlcm5lbC1kb2MgYi9zY3JpcHRzL2tlcm5lbC1kb2MKPiBpbmRleCAzODUwYzFlLi4x MmExMDZjIDEwMDc1NQo+IC0tLSBhL3NjcmlwdHMva2VybmVsLWRvYwo+ICsrKyBiL3NjcmlwdHMv a2VybmVsLWRvYwo+IEBAIC0yODgsNiArMjg4LDcgQEAgbXkgJHVzZV9tYXJrZG93biA9IDA7Cj4g IG15ICR2ZXJib3NlID0gMDsKPiAgbXkgJG91dHB1dF9tb2RlID0gIm1hbiI7Cj4gIG15ICRvdXRw dXRfcHJlZm9ybWF0dGVkID0gMDsKPiArbXkgJG91dHB1dF9tYXJrZG93bl9ub3BhcmEgPSAwOwo+ ICBteSAkbm9fZG9jX3NlY3Rpb25zID0gMDsKPiAgbXkgQGhpZ2hsaWdodHMgPSBAaGlnaGxpZ2h0 c19tYW47Cj4gIG15ICRibGFua2xpbmUgPSAkYmxhbmtsaW5lX21hbjsKPiBAQCAtNTI5LDggKzUz MCwxMSBAQCBzdWIgbWFya2Rvd25fdG9fZG9jYm9vayB7Cj4gIAljbG9zZShDSExEX09VVCk7Cj4g IAljbG9zZShDSExEX0VSUik7Cj4gIAo+IC0JIyBwYW5kb2MgaW5zaXN0cyBpbiBhZGRpbmcgTWFp biA8cGFyYT48L3BhcmE+LCB3ZSBzaG91bGQgcmVtb3ZlIHRoZW0uCj4gLQkkY29udGVudCA9fiBz OlxBXHMqPHBhcmE+XHMqXG4oLiopXG48L3BhcmE+XFokOiQxOmVnc207Cj4gKwlpZiAoJG91dHB1 dF9tYXJrZG93bl9ub3BhcmEpIHsKPiArCQkjIHBhbmRvYyBpbnNpc3RzIGluIGFkZGluZyBNYWlu IDxwYXJhPjwvcGFyYT4sIHNvbWV0aW1lcyB3ZQo+ICsJCSMgd2FudCB0byByZW1vdmUgdGhlbS4K PiArCQkkY29udGVudCA9fiBzOlxBXHMqPHBhcmE+XHMqXG4oLiopXG48L3BhcmE+XFokOiQxOmVn c207Cj4gKwl9Cj4gIAo+ICAJcmV0dXJuICRjb250ZW50Owo+ICB9Cj4gQEAgLTYwNSw3ICs2MDks NyBAQCBzdWIgb3V0cHV0X2hpZ2hsaWdodCB7Cj4gIAkgICAgJGxpbmUgPX4gcy9eXHMqLy87Cj4g IAl9Cj4gIAlpZiAoJGxpbmUgZXEgIiIpewo+IC0JICAgIGlmICghICRvdXRwdXRfcHJlZm9ybWF0 dGVkKSB7Cj4gKwkgICAgaWYgKCEgJG91dHB1dF9wcmVmb3JtYXR0ZWQgJiYgISAkdXNlX21hcmtk b3duKSB7Cj4gIAkJcHJpbnQgJGxpbmVwcmVmaXgsIGxvY2FsX3VuZXNjYXBlKCRibGFua2xpbmUp Owo+ICAJICAgIH0KPiAgCX0gZWxzZSB7Cj4gQEAgLTEwMjYsNyArMTAzMCw3IEBAIHN1YiBvdXRw dXRfc2VjdGlvbl94bWwoJSkgewo+ICAJICAgICMgcHJvZ3JhbWxpc3RpbmcgaXMgYWxyZWFkeSBp bmNsdWRlZCBieSBwYW5kb2MKPiAgCSAgICBwcmludCAiPHByb2dyYW1saXN0aW5nPlxuIiB1bmxl c3MgJHVzZV9tYXJrZG93bjsKPiAgCSAgICAkb3V0cHV0X3ByZWZvcm1hdHRlZCA9IDE7Cj4gLQl9 IGVsc2Ugewo+ICsJfSBlbHNpZiAoISAkdXNlX21hcmtkb3duKSB7Cj4gIAkgICAgcHJpbnQgIjxw YXJhPlxuIjsKPiAgCX0KPiAgCW91dHB1dF9oaWdobGlnaHQoJGFyZ3N7J3NlY3Rpb25zJ317JHNl Y3Rpb259KTsKPiBAQCAtMTAzNCw3ICsxMDM4LDcgQEAgc3ViIG91dHB1dF9zZWN0aW9uX3htbCgl KSB7Cj4gIAlpZiAoJHNlY3Rpb24gPX4gbS9FWEFNUExFL2kpIHsKPiAgCSAgICBwcmludCAiPC9w cm9ncmFtbGlzdGluZz5cbiIgdW5sZXNzICR1c2VfbWFya2Rvd247Cj4gIAkgICAgcHJpbnQgIjwv aW5mb3JtYWxleGFtcGxlPlxuIjsKPiAtCX0gZWxzZSB7Cj4gKwl9IGVsc2lmICghICR1c2VfbWFy a2Rvd24pIHsKPiAgCSAgICBwcmludCAiPC9wYXJhPlxuIjsKPiAgCX0KPiAgCXByaW50ICI8L3Jl ZnNlY3QxPlxuIjsKPiBAQCAtMTA2Niw3ICsxMDcwLDkgQEAgc3ViIG91dHB1dF9mdW5jdGlvbl94 bWwoJSkgewo+ICAgICAgcHJpbnQgIiA8cmVmbmFtZT4iIC4gJGFyZ3N7J2Z1bmN0aW9uJ30gLiAi PC9yZWZuYW1lPlxuIjsKPiAgICAgIHByaW50ICIgPHJlZnB1cnBvc2U+XG4iOwo+ICAgICAgcHJp bnQgIiAgIjsKPiArICAgICRvdXRwdXRfbWFya2Rvd25fbm9wYXJhID0gMTsKPiAgICAgIG91dHB1 dF9oaWdobGlnaHQgKCRhcmdzeydwdXJwb3NlJ30pOwo+ICsgICAgJG91dHB1dF9tYXJrZG93bl9u b3BhcmEgPSAwOwo+ICAgICAgcHJpbnQgIiA8L3JlZnB1cnBvc2U+XG4iOwo+ICAgICAgcHJpbnQg IjwvcmVmbmFtZWRpdj5cbiI7Cj4gIAo+IEBAIC0xMTA0LDEwICsxMTEwLDEyIEBAIHN1YiBvdXRw dXRfZnVuY3Rpb25feG1sKCUpIHsKPiAgCSAgICAkcGFyYW1ldGVyX25hbWUgPX4gcy9cWy4qLy87 Cj4gIAo+ICAJICAgIHByaW50ICIgIDx2YXJsaXN0ZW50cnk+XG4gICA8dGVybT48cGFyYW1ldGVy PiRwYXJhbWV0ZXI8L3BhcmFtZXRlcj48L3Rlcm0+XG4iOwo+IC0JICAgIHByaW50ICIgICA8bGlz dGl0ZW0+XG4gICAgPHBhcmE+XG4iOwo+ICsJICAgIHByaW50ICIgICA8bGlzdGl0ZW0+XG4iOwo+ ICsJICAgIHByaW50ICIgICAgPHBhcmE+XG4iIHVubGVzcyAkdXNlX21hcmtkb3duOwo+ICAJICAg ICRsaW5lcHJlZml4PSIgICAgICI7Cj4gIAkgICAgb3V0cHV0X2hpZ2hsaWdodCgkYXJnc3sncGFy YW1ldGVyZGVzY3MnfXskcGFyYW1ldGVyX25hbWV9KTsKPiAtCSAgICBwcmludCAiICAgIDwvcGFy YT5cbiAgIDwvbGlzdGl0ZW0+XG4gIDwvdmFybGlzdGVudHJ5PlxuIjsKPiArCSAgICBwcmludCAi ICAgIDwvcGFyYT5cbiIgdW5sZXNzICR1c2VfbWFya2Rvd247Cj4gKwkgICAgcHJpbnQgIiAgIDwv bGlzdGl0ZW0+XG4gIDwvdmFybGlzdGVudHJ5PlxuIjsKPiAgCX0KPiAgCXByaW50ICIgPC92YXJp YWJsZWxpc3Q+XG4iOwo+ICAgICAgfSBlbHNlIHsKPiBAQCAtMTE0Myw3ICsxMTUxLDkgQEAgc3Vi IG91dHB1dF9zdHJ1Y3RfeG1sKCUpIHsKPiAgICAgIHByaW50ICIgPHJlZm5hbWU+IiAuICRhcmdz eyd0eXBlJ30gLiAiICIgLiAkYXJnc3snc3RydWN0J30gLiAiPC9yZWZuYW1lPlxuIjsKPiAgICAg IHByaW50ICIgPHJlZnB1cnBvc2U+XG4iOwo+ICAgICAgcHJpbnQgIiAgIjsKPiArICAgICRvdXRw dXRfbWFya2Rvd25fbm9wYXJhID0gMTsKPiAgICAgIG91dHB1dF9oaWdobGlnaHQgKCRhcmdzeydw dXJwb3NlJ30pOwo+ICsgICAgJG91dHB1dF9tYXJrZG93bl9ub3BhcmEgPSAwOwo+ICAgICAgcHJp bnQgIiA8L3JlZnB1cnBvc2U+XG4iOwo+ICAgICAgcHJpbnQgIjwvcmVmbmFtZWRpdj5cbiI7Cj4g IAo+IEBAIC0xMTk2LDkgKzEyMDYsMTEgQEAgc3ViIG91dHB1dF9zdHJ1Y3RfeG1sKCUpIHsKPiAg ICAgICAgKCRhcmdzeydwYXJhbWV0ZXJkZXNjcyd9eyRwYXJhbWV0ZXJfbmFtZX0gbmUgJHVuZGVz Y3JpYmVkKSB8fCBuZXh0Owo+ICAgICAgICBwcmludCAiICAgIDx2YXJsaXN0ZW50cnk+IjsKPiAg ICAgICAgcHJpbnQgIiAgICAgIDx0ZXJtPiRwYXJhbWV0ZXI8L3Rlcm0+XG4iOwo+IC0gICAgICBw cmludCAiICAgICAgPGxpc3RpdGVtPjxwYXJhPlxuIjsKPiArICAgICAgcHJpbnQgIiAgICAgIDxs aXN0aXRlbT5cbiI7Cj4gKyAgICAgIHByaW50ICIgICAgICAgICA8cGFyYT5cbiIgdW5sZXNzICR1 c2VfbWFya2Rvd247Cj4gICAgICAgIG91dHB1dF9oaWdobGlnaHQoJGFyZ3N7J3BhcmFtZXRlcmRl c2NzJ317JHBhcmFtZXRlcl9uYW1lfSk7Cj4gLSAgICAgIHByaW50ICIgICAgICA8L3BhcmE+PC9s aXN0aXRlbT5cbiI7Cj4gKyAgICAgIHByaW50ICIgICAgICAgICA8L3BhcmE+XG4iIHVubGVzcyAk dXNlX21hcmtkb3duOwo+ICsgICAgICBwcmludCAiICAgICAgPC9saXN0aXRlbT5cbiI7Cj4gICAg ICAgIHByaW50ICIgICAgPC92YXJsaXN0ZW50cnk+XG4iOwo+ICAgICAgfQo+ICAgICAgcHJpbnQg IiAgPC92YXJpYWJsZWxpc3Q+XG4iOwo+IEBAIC0xMjM3LDcgKzEyNDksOSBAQCBzdWIgb3V0cHV0 X2VudW1feG1sKCUpIHsKPiAgICAgIHByaW50ICIgPHJlZm5hbWU+ZW51bSAiIC4gJGFyZ3N7J2Vu dW0nfSAuICI8L3JlZm5hbWU+XG4iOwo+ICAgICAgcHJpbnQgIiA8cmVmcHVycG9zZT5cbiI7Cj4g ICAgICBwcmludCAiICAiOwo+ICsgICAgJG91dHB1dF9tYXJrZG93bl9ub3BhcmEgPSAxOwo+ICAg ICAgb3V0cHV0X2hpZ2hsaWdodCAoJGFyZ3N7J3B1cnBvc2UnfSk7Cj4gKyAgICAkb3V0cHV0X21h cmtkb3duX25vcGFyYSA9IDA7Cj4gICAgICBwcmludCAiIDwvcmVmcHVycG9zZT5cbiI7Cj4gICAg ICBwcmludCAiPC9yZWZuYW1lZGl2PlxuIjsKPiAgCj4gQEAgLTEyNjcsOSArMTI4MSwxMSBAQCBz dWIgb3V0cHV0X2VudW1feG1sKCUpIHsKPiAgCj4gICAgICAgIHByaW50ICIgICAgPHZhcmxpc3Rl bnRyeT4iOwo+ICAgICAgICBwcmludCAiICAgICAgPHRlcm0+JHBhcmFtZXRlcjwvdGVybT5cbiI7 Cj4gLSAgICAgIHByaW50ICIgICAgICA8bGlzdGl0ZW0+PHBhcmE+XG4iOwo+ICsgICAgICBwcmlu dCAiICAgICAgPGxpc3RpdGVtPlxuIjsKPiArICAgICAgcHJpbnQgIiAgICAgICAgIDxwYXJhPlxu IiB1bmxlc3MgJHVzZV9tYXJrZG93bjsKPiAgICAgICAgb3V0cHV0X2hpZ2hsaWdodCgkYXJnc3sn cGFyYW1ldGVyZGVzY3MnfXskcGFyYW1ldGVyX25hbWV9KTsKPiAtICAgICAgcHJpbnQgIiAgICAg IDwvcGFyYT48L2xpc3RpdGVtPlxuIjsKPiArICAgICAgcHJpbnQgIiAgICAgICAgIDwvcGFyYT5c biIgdW5sZXNzICR1c2VfbWFya2Rvd247Cj4gKyAgICAgIHByaW50ICIgICAgICA8L2xpc3RpdGVt PlxuIjsKPiAgICAgICAgcHJpbnQgIiAgICA8L3Zhcmxpc3RlbnRyeT5cbiI7Cj4gICAgICB9Cj4g ICAgICBwcmludCAiICA8L3ZhcmlhYmxlbGlzdD5cbiI7Cj4gQEAgLTEzMzUsMTQgKzEzNTEsMTQg QEAgc3ViIG91dHB1dF9ibG9ja2hlYWRfeG1sKCUpIHsKPiAgCWlmICgkc2VjdGlvbiA9fiBtL0VY QU1QTEUvaSkgewo+ICAJICAgIHByaW50ICI8ZXhhbXBsZT48cGFyYT5cbiI7Cj4gIAkgICAgJG91 dHB1dF9wcmVmb3JtYXR0ZWQgPSAxOwo+IC0JfSBlbHNlIHsKPiArCX0gZWxzaWYgKCEgJHVzZV9t YXJrZG93bikgewo+ICAJICAgIHByaW50ICI8cGFyYT5cbiI7Cj4gIAl9Cj4gIAlvdXRwdXRfaGln aGxpZ2h0KCRhcmdzeydzZWN0aW9ucyd9eyRzZWN0aW9ufSk7Cj4gIAkkb3V0cHV0X3ByZWZvcm1h dHRlZCA9IDA7Cj4gIAlpZiAoJHNlY3Rpb24gPX4gbS9FWEFNUExFL2kpIHsKPiAgCSAgICBwcmlu dCAiPC9wYXJhPjwvZXhhbXBsZT5cbiI7Cj4gLQl9IGVsc2Ugewo+ICsJfSBlbHNpZiAoISAkdXNl X21hcmtkb3duKSB7Cj4gIAkgICAgcHJpbnQgIjwvcGFyYT4iOwo+ICAJfQo+ICAJaWYgKCEkYXJn c3snY29udGVudC1vbmx5J30pIHsKPiBAQCAtMjY4NCw3ICsyNzAwLDExIEBAIHN1YiBwcm9jZXNz X2ZpbGUoJCkgewo+ICAJCXsKPiAgCQkJaWYgKCAkMSBlcSAiIiApCj4gIAkJCXsKPiAtCQkJCSRj b250ZW50cyAuPSAkYmxhbmtsaW5lOwo+ICsJCQkJaWYgKCR1c2VfbWFya2Rvd24pIHsKPiArCQkJ CQkkY29udGVudHMgLj0gIlxuIjsKPiArCQkJCX0gZWxzZSB7Cj4gKwkJCQkJJGNvbnRlbnRzIC49 ICRibGFua2xpbmU7Cj4gKwkJCQl9Cj4gIAkJCX0KPiAgCQkJZWxzZQo+ICAJCQl7Cj4gCgpIZXkg Sm9uYXRoYW4sCgpEaWQgeW91IGZpbmQgdGltZSB0byBjaGVjayB0aGlzIHBhdGNoPyBBcyB5b3Ug bWVudGlvbmVkIHRoYXQgeW91IGFwcGxpZWQKdGhlIE1hcmtkb3duIHN1cHBvcnQgZm9yIHRoZSBs aW51eC1uZXh0IHRyZWUsIHRoaXMgcGF0Y2ggbWlnaHQgYmUgbmVlZGVkCihtYXliZSAid2FudGVk IiBpcyBhIGJldHRlciB3b3JkKS4KCkludGVsIGd1eXMgYXJlIHdvcmtpbmcgb24gaW1wcm92aW5n IGRvY3VtZW50YXRpb24gYW5kIEkgYmVsaWV2ZSB0aGV5Cm5lZWQgdGhpcy4KClRoYW5rcywKCkRh bmlsbwpfX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fXwpJbnRl bC1nZnggbWFpbGluZyBsaXN0CkludGVsLWdmeEBsaXN0cy5mcmVlZGVza3RvcC5vcmcKaHR0cDov L2xpc3RzLmZyZWVkZXNrdG9wLm9yZy9tYWlsbWFuL2xpc3RpbmZvL2ludGVsLWdmeAo= From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755368AbbIAR6c (ORCPT ); Tue, 1 Sep 2015 13:58:32 -0400 Received: from bhuna.collabora.co.uk ([93.93.135.160]:55924 "EHLO bhuna.collabora.co.uk" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754352AbbIAR5m (ORCPT ); Tue, 1 Sep 2015 13:57:42 -0400 Subject: Re: [PATCH] scripts/kernel-doc: Improve Markdown results Cc: Randy Dunlap , Daniel Vetter , Laurent Pinchart , Jonathan Corbet , Herbert Xu , Stephan Mueller , Michal Marek , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, intel-gfx , dri-devel , Graham Whaley References: <1440185942-31030-1-git-send-email-danilo.cesar@collabora.co.uk> From: Danilo Cesar Lemes de Paula X-Enigmail-Draft-Status: N1110 Message-ID: <55E5E70D.4050201@collabora.co.uk> Date: Tue, 1 Sep 2015 14:57:33 -0300 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.1.0 MIME-Version: 1.0 In-Reply-To: <1440185942-31030-1-git-send-email-danilo.cesar@collabora.co.uk> Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 8bit To: unlisted-recipients:; (no To-header on input) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On 08/21/2015 04:39 PM, Danilo Cesar Lemes de Paula wrote: > Using pandoc as the Markdown engine cause some minor side effects as > pandoc includes main tags for almost everything. > Original Markdown support approach removes those main tags, but it caused > some inconsistencies when that tag is not the main one, like: > .. > ... > > As kernel-doc was already including a tag, it causes the presence > of double tags (), which is not supported by DocBook > spec. > > Html target gets away with it, so it causes no harm, although other > targets might not be so lucky (pdf as example). > > We're now delegating the inclusion of the main tag to pandoc > only, as it knows when it's necessary or not. > > That behavior causes a corner case, the only situation where we're > certainly that is not needed, which is the content. > For those cases, we're using a $output_markdown_nopara = 1 control var. > > Signed-off-by: Danilo Cesar Lemes de Paula > Cc: Randy Dunlap > Cc: Daniel Vetter > Cc: Laurent Pinchart > Cc: Jonathan Corbet > Cc: Herbert Xu > Cc: Stephan Mueller > Cc: Michal Marek > Cc: linux-kernel@vger.kernel.org > Cc: linux-doc@vger.kernel.org > Cc: intel-gfx > Cc: dri-devel > Cc: Graham Whaley > --- > Thanks to Graham Whaley who helped me to debug this. > > scripts/kernel-doc | 48 ++++++++++++++++++++++++++++++++++-------------- > 1 file changed, 34 insertions(+), 14 deletions(-) > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > index 3850c1e..12a106c 100755 > --- a/scripts/kernel-doc > +++ b/scripts/kernel-doc > @@ -288,6 +288,7 @@ my $use_markdown = 0; > my $verbose = 0; > my $output_mode = "man"; > my $output_preformatted = 0; > +my $output_markdown_nopara = 0; > my $no_doc_sections = 0; > my @highlights = @highlights_man; > my $blankline = $blankline_man; > @@ -529,8 +530,11 @@ sub markdown_to_docbook { > close(CHLD_OUT); > close(CHLD_ERR); > > - # pandoc insists in adding Main , we should remove them. > - $content =~ s:\A\s*\s*\n(.*)\n\Z$:$1:egsm; > + if ($output_markdown_nopara) { > + # pandoc insists in adding Main , sometimes we > + # want to remove them. > + $content =~ s:\A\s*\s*\n(.*)\n\Z$:$1:egsm; > + } > > return $content; > } > @@ -605,7 +609,7 @@ sub output_highlight { > $line =~ s/^\s*//; > } > if ($line eq ""){ > - if (! $output_preformatted) { > + if (! $output_preformatted && ! $use_markdown) { > print $lineprefix, local_unescape($blankline); > } > } else { > @@ -1026,7 +1030,7 @@ sub output_section_xml(%) { > # programlisting is already included by pandoc > print "\n" unless $use_markdown; > $output_preformatted = 1; > - } else { > + } elsif (! $use_markdown) { > print "\n"; > } > output_highlight($args{'sections'}{$section}); > @@ -1034,7 +1038,7 @@ sub output_section_xml(%) { > if ($section =~ m/EXAMPLE/i) { > print "\n" unless $use_markdown; > print "\n"; > - } else { > + } elsif (! $use_markdown) { > print "\n"; > } > print "\n"; > @@ -1066,7 +1070,9 @@ sub output_function_xml(%) { > print " " . $args{'function'} . "\n"; > print " \n"; > print " "; > + $output_markdown_nopara = 1; > output_highlight ($args{'purpose'}); > + $output_markdown_nopara = 0; > print " \n"; > print "\n"; > > @@ -1104,10 +1110,12 @@ sub output_function_xml(%) { > $parameter_name =~ s/\[.*//; > > print " \n $parameter\n"; > - print " \n \n"; > + print " \n"; > + print " \n" unless $use_markdown; > $lineprefix=" "; > output_highlight($args{'parameterdescs'}{$parameter_name}); > - print " \n \n \n"; > + print " \n" unless $use_markdown; > + print " \n \n"; > } > print " \n"; > } else { > @@ -1143,7 +1151,9 @@ sub output_struct_xml(%) { > print " " . $args{'type'} . " " . $args{'struct'} . "\n"; > print " \n"; > print " "; > + $output_markdown_nopara = 1; > output_highlight ($args{'purpose'}); > + $output_markdown_nopara = 0; > print " \n"; > print "\n"; > > @@ -1196,9 +1206,11 @@ sub output_struct_xml(%) { > ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; > print " "; > print " $parameter\n"; > - print " \n"; > + print " \n"; > + print " \n" unless $use_markdown; > output_highlight($args{'parameterdescs'}{$parameter_name}); > - print " \n"; > + print " \n" unless $use_markdown; > + print " \n"; > print " \n"; > } > print " \n"; > @@ -1237,7 +1249,9 @@ sub output_enum_xml(%) { > print " enum " . $args{'enum'} . "\n"; > print " \n"; > print " "; > + $output_markdown_nopara = 1; > output_highlight ($args{'purpose'}); > + $output_markdown_nopara = 0; > print " \n"; > print "\n"; > > @@ -1267,9 +1281,11 @@ sub output_enum_xml(%) { > > print " "; > print " $parameter\n"; > - print " \n"; > + print " \n"; > + print " \n" unless $use_markdown; > output_highlight($args{'parameterdescs'}{$parameter_name}); > - print " \n"; > + print " \n" unless $use_markdown; > + print " \n"; > print " \n"; > } > print " \n"; > @@ -1335,14 +1351,14 @@ sub output_blockhead_xml(%) { > if ($section =~ m/EXAMPLE/i) { > print "\n"; > $output_preformatted = 1; > - } else { > + } elsif (! $use_markdown) { > print "\n"; > } > output_highlight($args{'sections'}{$section}); > $output_preformatted = 0; > if ($section =~ m/EXAMPLE/i) { > print "\n"; > - } else { > + } elsif (! $use_markdown) { > print ""; > } > if (!$args{'content-only'}) { > @@ -2684,7 +2700,11 @@ sub process_file($) { > { > if ( $1 eq "" ) > { > - $contents .= $blankline; > + if ($use_markdown) { > + $contents .= "\n"; > + } else { > + $contents .= $blankline; > + } > } > else > { > Hey Jonathan, Did you find time to check this patch? As you mentioned that you applied the Markdown support for the linux-next tree, this patch might be needed (maybe "wanted" is a better word). Intel guys are working on improving documentation and I believe they need this. Thanks, Danilo