Formatting of README files

classic Classic list List threaded Threaded
10 messages Options
Chris Sherlock Chris Sherlock
Reply | Threaded
Open this post in threaded view
|

Formatting of README files

Hi all, 

I noticed that there is some minor formatting capabilities on the docs.libreoffice.org website for readmes. 

e.g. http://docs.libreoffice.org/vcl.html shows headings, which uses Wikimedia style double-equals signs before and after the heading text. 

Are there any other formatting marks? If there are, are they documented anywhere?

Also, what would the feasibility of using Markdown syntax, ala github.io?

Chris

_______________________________________________
LibreOffice mailing list
[hidden email]
http://lists.freedesktop.org/mailman/listinfo/libreoffice
Miklos Vajna-4 Miklos Vajna-4
Reply | Threaded
Open this post in threaded view
|

Re: Formatting of README files

Hi Chris,

On Tue, Nov 25, 2014 at 01:17:07PM +1100, Chris Sherlock <[hidden email]> wrote:

> I noticed that there is some minor formatting capabilities on the
> docs.libreoffice.org website for readmes.
>
> e.g. http://docs.libreoffice.org/vcl.html shows headings, which uses
> Wikimedia style double-equals signs before and after the heading text.
>
> Are there any other formatting marks? If there are, are they documented
> anywhere?
>
> Also, what would the feasibility of using Markdown syntax, ala github.io?
As I noted on IRC, solenv/bin/mkdocs.sh takes care of processing these
README files. If you want to tweak the syntax there, please submit a
patch against mkdocs.sh (and ideally the same patch adjusting the
existing README files if the syntax is not backwards-compatible).

Regards,

Miklos

_______________________________________________
LibreOffice mailing list
[hidden email]
http://lists.freedesktop.org/mailman/listinfo/libreoffice

signature.asc (188 bytes) Download Attachment
Kohei Yoshida-7 Kohei Yoshida-7
Reply | Threaded
Open this post in threaded view
|

Re: Formatting of README files

In reply to this post by Chris Sherlock
On Tue, 2014-11-25 at 13:17 +1100, Chris Sherlock wrote:

>
> Also, what would the feasibility of using Markdown syntax, ala
> github.io?

Actually this may be an interesting choice for us in the long run.
Markdown[1] seems to be popular syntax of choice for README files in
many open source projects.  Rather than inventing our own syntax,
sticking with an already existing standard is probably a good idea IMO.

Kohei

[1] http://en.wikipedia.org/wiki/Markdown


_______________________________________________
LibreOffice mailing list
[hidden email]
http://lists.freedesktop.org/mailman/listinfo/libreoffice
Tor Lillqvist-2 Tor Lillqvist-2
Reply | Threaded
Open this post in threaded view
|

Re: Formatting of README files

I wonder if it is politically controversial to be seen as "supporting" a markup language, though, the antithesis to WYSIWYG... Even if it is a quite new and minimal markup language, that doesn't pretend to be even close to full-featured (like troff or TeX).

I can imagine the reaction among the trolling population, "oh, so LibreOffice developers don't like their own software, but prefer to write their documentation in this sixties-style markup language, ha ha ha".

But yeah, one should ignore trolls. I actually like the idea quite much.

--tml

_______________________________________________
LibreOffice mailing list
[hidden email]
http://lists.freedesktop.org/mailman/listinfo/libreoffice
Bjoern Michaelsen Bjoern Michaelsen
Reply | Threaded
Open this post in threaded view
|

Re: Formatting of README files

Hi,

On Thu, Nov 27, 2014 at 01:16:14AM +0200, Tor Lillqvist wrote:
> I wonder if it is politically controversial to be seen as "supporting" a
> markup language, though, the antithesis to WYSIWYG... Even if it is a quite
> new and minimal markup language, that doesn't pretend to be even close to
> full-featured (like troff or TeX).

If one of our wonderful Document Liberation guys would volunteer to mentor
that, we could have an Easy Hack making LibreOffice exporting/importing
MarkDown would be awesome ...

> I can imagine the reaction among the trolling population, "oh, so
> LibreOffice developers don't like their own software, but prefer to write
> their documentation in this sixties-style markup language, ha ha ha".
>
> But yeah, one should ignore trolls. I actually like the idea quite much.

... and allows us to then direct those trolls towards that Easy Hack with a
calm and dry show-me-the-code/put-up-or-shut-up combo.

Personally MarkDown seems fine to me and we are actually already using it
elsewhere in the project (e.g. Infra docs, Redmine) IIRC.

Best,

Bjoern
_______________________________________________
LibreOffice mailing list
[hidden email]
http://lists.freedesktop.org/mailman/listinfo/libreoffice
Wols Lists Wols Lists
Reply | Threaded
Open this post in threaded view
|

Re: Formatting of README files

In reply to this post by Tor Lillqvist-2
On 26/11/2014 23:16, Tor Lillqvist wrote:

> I wonder if it is politically controversial to be seen as "supporting"
> a markup language, though, the antithesis to WYSIWYG... Even if it is
> a quite new and minimal markup language, that doesn't pretend to be
> even close to full-featured (like troff or TeX).
>
> I can imagine the reaction among the trolling population, "oh, so
> LibreOffice developers don't like their own software, but prefer to
> write their documentation in this sixties-style markup language, ha ha
> ha".
>
>
Actually, the KILLER feature of WordPerfect was always its markup mode.
And the sooner we can get that (reveal codes) working in Writer, the
better!!! Okay, I might be an old-school typist, but imho pure wysiwyg
is an AWFUL idea. Dragging stuff around with a mouse is an awful way of
getting stuff in the right place!

I've spent my own money on WordPerfect in the past, and would do so
again if I had the money to spare - that feature is THAT important to
me. Unfortunately, because MS view WP as dangerous competition, my old
copies don't work (very well) any more. Seriously, markup-mode IS a
killer feature. (Unfortunately, today's vulgate have never known
anything other than wysiwyg and don't know what they're missing :-(

Cheers,
Wol
_______________________________________________
LibreOffice mailing list
[hidden email]
http://lists.freedesktop.org/mailman/listinfo/libreoffice
Thorsten Behrens Thorsten Behrens
Reply | Threaded
Open this post in threaded view
|

Re: Formatting of README files

In reply to this post by Bjoern Michaelsen
Bjoern Michaelsen wrote:
> If one of our wonderful Document Liberation guys would volunteer to mentor
> that, we could have an Easy Hack making LibreOffice exporting/importing
> MarkDown would be awesome ...
>
FWIW, there's

 - pandoc for conversion to odt:
   http://johnmacfarlane.net/BayHac2014/doc/pandoc/Text-Pandoc-Writers-OpenDocument.html
 - odpgen for conversion to odp:
   https://github.com/thorstenb/odpgen/blob/master/README.md
   (shameless plug)

I think attempting to export from LibreOffice is really pointless.

Cheers,

-- Thorsten

_______________________________________________
LibreOffice mailing list
[hidden email]
http://lists.freedesktop.org/mailman/listinfo/libreoffice

signature.asc (985 bytes) Download Attachment
Christian Lohmaier-3 Christian Lohmaier-3
Reply | Threaded
Open this post in threaded view
|

Re: Formatting of README files

In reply to this post by Kohei Yoshida-7

Hi *,

Am 26.11.2014 23:53 schrieb "Kohei Yoshida" <[hidden email]>:
> On Tue, 2014-11-25 at 13:17 +1100, Chris Sherlock wrote:
>
> >
> > Also, what would the feasibility of using Markdown syntax, ala
> > github.io?
>
> Actually this may be an interesting choice for us in the long run.
> Markdown[1] seems to be popular syntax of choice for README files in
> many open source projects. 

Silverstripe also uses markdown as basis for their documentation, although with some additions.

http://doc.silverstripe.org/framework/en/trunk/misc/ss-markdown

Or in other words: when using markdown, creating automatic TOC/listings and serving it as HTML/creating static output in html is no problem at all...

Ciao
Christian


_______________________________________________
LibreOffice mailing list
[hidden email]
http://lists.freedesktop.org/mailman/listinfo/libreoffice
Christian Lohmaier-3 Christian Lohmaier-3
Reply | Threaded
Open this post in threaded view
|

Re: Formatting of README files

In reply to this post by Bjoern Michaelsen

Hi *,

Am 27.11.2014 00:29 schrieb "Bjoern Michaelsen" <[hidden email]>:
>
> On Thu, Nov 27, 2014 at 01:16:14AM +
> Personally MarkDown seems fine to me and we are actually already using it
> elsewhere in the project (e.g. Infra docs, Redmine) IIRC.

For infra-internal docs we use rst... (But that's less suitable for translators)

Ciao
Christian


_______________________________________________
LibreOffice mailing list
[hidden email]
http://lists.freedesktop.org/mailman/listinfo/libreoffice
Bjoern Michaelsen Bjoern Michaelsen
Reply | Threaded
Open this post in threaded view
|

Re: Formatting of README files

In reply to this post by Thorsten Behrens
Hi,

On Fri, Nov 28, 2014 at 01:33:36PM +0100, Thorsten Behrens wrote:
> I think attempting to export from LibreOffice is really pointless.

I would not be too sure of that. For the audience of this list: absolutely. For the
users of our product: unlikely. RST, MarkDown, MediaWiki are transparent to
this lists audience, but quite likely not so much for the rest of the world --
so roundtripping those "formats" to WYSIWYG might be appreciated by them.

Anyway, this is a distraction, sorry for the noise.

Best,

Bjoern
_______________________________________________
LibreOffice mailing list
[hidden email]
http://lists.freedesktop.org/mailman/listinfo/libreoffice