discuss: Thread: Formats

Please forgive me for beating a very dead horse, but I've been away for
a few days and I'd like to add something that I hope will be useful.

I am not going to use docbook or linuxdoc.  I think they are too time
consuming to learn and the energy required to use them is greater than
benefit.

Here's what I suggest: use whatever you want and stop complaining. Why
do I say that? Am I trolling for a flame war?  No. There are some
wonderful apps out there that can convert whatever format that you want
to use to docbook. The primary one is pandoc (http://pandoc.org/). 
Using Ubuntu 15.10, the current version of pandoc can work with the
following formats:

Input formats:  docbook, docx, epub, haddock, html, json, latex, markdown,
                markdown_github, markdown_mmd, markdown_phpextra,
                markdown_strict, mediawiki, native, opml, org, rst, t2t,
                textile, twiki
Output formats: asciidoc, beamer, context, docbook, docx, dokuwiki,
dzslides,
                epub, epub3, fb2, haddock, html, html5, icml, json,
latex, man,
                markdown, markdown_github, markdown_mmd, markdown_phpextra,
                markdown_strict, mediawiki, native, odt, opendocument, opml,
                org, pdf*, plain, revealjs, rst, rtf, s5, slideous, slidy,
                texinfo, textile
                [*for pdf output, use latex or beamer and -o FILENAME.pdf]

Using this tool, you could literally write your guide in LibreOffice or
MS Word (if you so desire) and convert the docx file to docbook, ready
for upload to git.

The cli command would be:

$ pandoc -f docx -t docbook myHOWTO.docx -o myHOWTO.xml

It's really that simple, though I can't promise you that tweaks won't be
required to get the file perfect. Pandoc isn't the only tool that does
this kind of thing, but it's quite mature and is still being developed.
I think it's a great solution to write how you want without needing to
bicker over formats.

Also, this week I've done a lot of reading this week about lightweight
markup languages: markdown, restructured text, asciidoc, and emacs
org-mode.  All of these are very easy to learn and quick to implement
compared to other formats.  Personally, I'm going with LyX (it handles
docbook natively) and org-mode since I'm doing more of my work in a vm
without a gui and emacs makes it very easy.

Jason

Le 11/02/2016 18:55, J. S. Evans a écrit :

> I am not going to use docbook or linuxdoc.  I think they are too time
> consuming to learn and the energy required to use them is greater than
> benefit.

you can't really, and the minimal knowledge is very small.

you can't if, like you post seems to say, you intend to export it to 
docbook afterward.

Simply because you can't export to docbook (or any other format) 
anything not already prepared to be so - the only other way is to make a 
snapshot (jpd, image) of the document.

So you need to know howto write docbook to be able to build the document 
in the first place.

read the author guide (at least the wiki version, I don't remember the 
other one). using a template makes it very easy to write any doc.

one have only to make consistent titles / lists and avoid tables.

the only thing not clear at the time was what to do with images, because 
images had to be avoided to cope with slow bandwith that was regular.

You can very easily test writing in the wiki (and then export, all this 
is documented) if you work online, or use LibreOffice and write to 
Docbook xml, even begin to write docbook with LibreOffice.

the main problem is that anybody have to refrain from trying to make 
fine layout. Doc do not mind layout, only structure and content works

jdd

Quoting J. S. Evans ####@####.####

> Here's what I suggest: use whatever you want and stop complaining. 

Sure, why not?

To the best of my recollection, all tools are OK for producing LDP
content, and all contributions have been accepted without banning any
specific toolsets or formats.

pandoc is very cool, indeed.  Thanks for the tip and favourable mention.

> Also, this week I've done a lot of reading this week about lightweight
> markup languages: markdown, restructured text, asciidoc, and emacs
> org-mode.  All of these are very easy to learn and quick to implement
> compared to other formats.

Concur.  I personally find that markdown hits the sweet spot, but
they're all good.

On Monday, February 22, 2016 05:56:20 AM Rick Moen wrote:
> Quoting J. S. Evans ####@####.####
> > Also, this week I've done a lot of reading this week about lightweight
> > markup languages: markdown, restructured text, asciidoc, and emacs
> > org-mode.  All of these are very easy to learn and quick to implement
> > compared to other formats.
> 
> Concur.  I personally find that markdown hits the sweet spot, but
> they're all good.

I'd add to this list several (maybe all / any) wiki markup languages.  I like 
TML (TWiki Markup Language), and it is supported by PanDoc, iirc.

> On Mon, Feb 22, 2016 at 02:56:20AM -0800, Rick Moen wrote:
>Quoting J. S. Evans ####@####.####
>
>> Here's what I suggest: use whatever you want and stop complaining. 
>
>Sure, why not?
>
>To the best of my recollection, all tools are OK for producing LDP
>content, and all contributions have been accepted without banning any
>specific toolsets or formats.

Amen to the above!

-- 
Roger
http://rogerx.freeshell.org/

On Thu, Feb 11, 2016 at 06:55:06PM +0100, J. S. Evans wrote:
> I am not going to use docbook or linuxdoc.  I think they are too time
> consuming to learn and the energy required to use them is greater than
> benefit.
I found that using linuxdoc to create a table of contents (TOC) was a lot
faster than doing it manually, counting the short time it took to figure
out how to use linuxdoc (starting with a linuxdoc template).  Linuxdoc is
about as easy as a wiki markup (without templates)
> 
> Here's what I suggest: use whatever you want and stop complaining. Why
> do I say that? Am I trolling for a flame war?  No. There are some
> wonderful apps out there that can convert whatever format that you want
> to use to docbook. The primary one is pandoc (http://pandoc.org/).
> Using Ubuntu 15.10, the current version of pandoc can work with the
> following formats:

I'll have to see it to believe it.  The automatic conversions at LDP from
linuxdoc to docbook contained a lot of wrong format.  If pandoc can do
what it claims, we can covert docbook to mediawiki.  But jdd said that it
didn't come out right when he tried to convert docbook to a wiki (but LDP
doesn't use mediawiki).  If pandoc works well, LDP could convert
everything to mediawiki provided it's easy to edit/test mediawiki.  What I
don't know is: how easy is it to convert mediawiki to get stand-alone
html.  The conversions done at wikipedia (using mediawiki) seem to not not
result in a stand-alone html doc, but need to have access to data on
wikipedia sites when displaying html on your screen.  There is also the
complexity of having a lot a special templates and add-ons.  (Continued near
end of this email)

> 
> Input formats:  docbook, docx, epub, haddock, html, json, latex,
> markdown, markdown_github, markdown_mmd, markdown_phpextra,
> markdown_strict, mediawiki, native, opml, org, rst, t2t, textile, twiki
>
Where is linuxdoc and plaintext in this list?  But as I recall one can
convert asciidoc to linuxdoc.

> Output formats: asciidoc, beamer, context, docbook, docx, dokuwiki,
> dzslides, epub, epub3, fb2, haddock, html, html5, icml, json, latex,
> man, markdown, markdown_github, markdown_mmd, markdown_phpextra,
> markdown_strict, mediawiki, native, odt, opendocument, opml, org, pdf*,
> plain, revealjs, rst, rtf, s5, slideous, slidy, texinfo, textile [*for
> pdf output, use latex or beamer and -o FILENAME.pdf]
> 
> Using this tool, you could literally write your guide in LibreOffice or
> MS Word (if you so desire) and convert the docx file to docbook, ready
> for upload to git.
> 
> The cli command would be:
> 
> $ pandoc -f docx -t docbook myHOWTO.docx -o myHOWTO.xml
> 
> It's really that simple, though I can't promise you that tweaks won't be
> required to get the file perfect. Pandoc isn't the only tool that does
> this kind of thing, but it's quite mature and is still being developed.
> I think it's a great solution to write how you want without needing to
> bicker over formats.
> 
> Also, this week I've done a lot of reading this week about lightweight
> markup languages: markdown, restructured text, asciidoc, and emacs
> org-mode.  All of these are very easy to learn and quick to implement
> compared to other formats.  Personally, I'm going with LyX (it handles
> docbook natively) and org-mode since I'm doing more of my work in a vm
> without a gui and emacs makes it very easy.

I haven't looked into it but there is a wiki called DokuWiki which is
open-source, designed for documentation.  I'm ignorant as to whether or not
it's easy to edit wiki docs offline and check to see if they display
correctly in html. 

When mentioning all feasible markup formats (including plain text which
needs to have at least and author and date) in LAG there needs to be a
link to other pages briefly describing their markup (with examples), etc
and hopefully containing enough info to get someone started writing.
Also, what about mentioning the how-to generator at :
   Linkname: The LDP HOWTO Generator
        URL: http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator.html
Does this work OK now?  It uses a template with instructions in the
template to create linuxdoc.

The post by jdd on this format thread is correct.  There is just no way to
create a Docbook file from say an html format.  html has no section heads
unless one has used the size of font to imply a section head in html.
html doesn't require an author or date, etc.

Should LDP accept all formats?  No. First of all, a doc needs to contain the
authors name, email (perhaps scrambled), and date of revision and a
perhaps a note as to whether or not the revision is minor.  There should
be preferred formats and a few formats that we suggest for authors who
have never used a format (other that plain text such as in email).
that doesn't convert to others


			David Lawyer

Quoting David Lawyer ####@####.####

> Should LDP accept all formats?  No.

Hold that thought for a moment.

> First of all, a doc needs to contain the authors name, email (perhaps
> scrambled), and date of revision and a perhaps a note as to whether or
> not the revision is minor.

So, if a good submission arrived in, say, plaintext or HTML that lacked
those elements, we volunteers would say something like 'Terrific
contribution, and thank you!  By the way, what's the author's name, date
of revision, and by the way is the revision minor?'  Right?  I think the
answer to that question is 'yes'.  So, in effect, that submision would
be gratefully resceived and we-all would add the missing elements as
prompted from the submitter.

(My recollection is that LDP also learned from past neglect about
explicit licensing terms, and would politely pursue the submitter to
secure a grant of some forkable-permissions licensing terms from the
copyright holder before merging the doc into LDP's collection.  Correct
me if I'm wrong, please.)

BTW, I will conditionally volunteer to help convert into reasonable
formats promising submissions arriving in strange format.
('Conditionally' means I reserve the right to say I'm busy or otherwise
unavailable at particular times, and of course there are many strange
formats I cannot parse, and possibly some for which I'd turn out to lack
time and patience.)

So, functionlly speaking, I'd suggest that no format is an automatic
deal-breaker, and it's not in LDP's interest to so suggest.

Le 24/02/2016 08:21, Rick Moen a écrit :

> (My recollection is that LDP also learned from past neglect about
> explicit licensing terms, and would politely pursue the submitter to
> secure a grant of some forkable-permissions licensing terms from the
> copyright holder before merging the doc into LDP's collection.  Correct
> me if I'm wrong, please.)

this is *mandatory*. Having no licence clearly indicated in the text, 
means that *nobody* is allowed to make any edit to the text. It was one 
of the main problem we had to revise the tldp docs.

then you have to define what ldp call "format".

I myself read it as text formatting rules, not as significant content, 
so even in clear raw text one can give name, licence and titles in a way 
clear enough for a human.

long time ago, we chooses moinmoin wiki for two reasons: much easier to 
maintain than mediawiki (the most attacked wiki, for obvious reasons), 
and built in convert to docbook.

Ldp should think twice before changing that...

jdd

Quoting Jean-Daniel Dodin ####@####.####

[licensing:]

> this is *mandatory*. 

Thank you.  (I was pretty sure I remembered correctly, but it's good to
hear that confirmed.)

> long time ago, we chooses moinmoin wiki for two reasons: much easier
> to maintain than mediawiki (the most attacked wiki, for obvious
> reasons), and built in convert to docbook.
> 
> Ldp should think twice before changing that...

MoinMoin is really good.  I have had enough experience with it to 
respect it highly.

Hello there,

>> Should LDP accept all formats?  No.
>
>Hold that thought for a moment.
>
>> First of all, a doc needs to contain the authors name, email (perhaps
>> scrambled), and date of revision and a perhaps a note as to whether or
>> not the revision is minor.
>
>So, if a good submission arrived in, say, plaintext or HTML that 
>lacked those elements, we volunteers would say something like 
>'Terrific contribution, and thank you!  By the way, what's the 
>author's name, date of revision, and by the way is the revision 
>minor?' Right?  I think the answer to that question is 'yes'.  So, 
>in effect, that submision would be gratefully resceived and we-all 
>would add the missing elements as prompted from the submitter.
>
>(My recollection is that LDP also learned from past neglect about 
>explicit licensing terms, and would politely pursue the submitter 
>to secure a grant of some forkable-permissions licensing terms from 
>the copyright holder before merging the doc into LDP's collection.  
>Correct me if I'm wrong, please.)

Yes.  This is the same old song about ensuring the document comes 
with a sensible (for our stewardship) license.

And, thanks to jdd and mhydra for listing them out a few years ago.

  http://wiki.tldp.org/Page_Status

(I would love to have a way to extract the license name from each of 
the documents in the code repository.  Kind of like the DOAP entries 
in Python's PyPI packages or Perl's CPAN bundles.  Something for 
the future.)

>BTW, I will conditionally volunteer to help convert into reasonable 
>formats promising submissions arriving in strange format. 
>('Conditionally' means I reserve the right to say I'm busy or 
>otherwise unavailable at particular times, and of course there are 
>many strange formats I cannot parse, and possibly some for which 
>I'd turn out to lack time and patience.)

Excellent, Rick!

Thank you,

-Martin

-- 
Martin A. Brown
http://linux-ip.net/