discuss: Thread: Formats

Hello,

>> 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.

>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.

I'll try out the LDP HOWTO Generator.  It is always nice to have an 
example.

On examples, we have (in the repository currently):

  howto/linuxdoc/Template-Linuxdoc-Small-HOWTO.sgml
  howto/linuxdoc/Template-Linuxdoc-Big-HOWTO.sgml
  howto/docbook/Template-Big-HOWTO/Template-Big-HOWTO.sgml

[I plan on switching Template-Big-HOWTO.sgml to DocBook XML 4.x.]

>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.

There probably are all sorts of tools for converting one way to 
another.  It makes sense to me to prefer storing documents in our 
repository in 'single-source' style documents, which can generate 
(directly), the desired outputs.

That's part of the reason why we have accepted Linuxdoc and DocBook 
(SGML and XML) variants in the past.

>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

Probably old news, but the LDP current supported formats (and 
preference status):

  preferred  Linuxdoc
  preferred  DocBook XML 4.x
  accepted   DocBook SGML 4.x
  accepted   DocBook SGML 3.x
  retired    WikiText [0]

I hope we can add another one or two soon.  I really like the 
single-source types, myself,

-Martin

 [0] Per discussion on this list a few weeks ago....

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

On Tue, Feb 23, 2016 at 11:21:06PM -0800, Rick Moen wrote:
> 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 submission would
> be gratefully received and we-all would add the missing elements as
> prompted from the submitter.

LDP would simply tell authors to put their name, the date, etc. at the
start of the doc, or it would be provided by a template (like for emails
or for the how-to generator that's still on the web).  Why would someone
refuse to do that?  It's so easy to do.  Of course an article needs a
title also.  There are always some exceptional cases that don't need to be
considered in advance (unless they would do significant harm to LDP).

> 
> (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 we need to revise the manifesto on that point, and I'll post here my
proposals.  Licensing conditions were removed from the wiki manifesto and
perhaps they should be put back.  We really need a CMS where the data on
licenses could be placed.  We already have such data but it's not in an
integrated cms.

> 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.)

What about volunteering to do something that has a higher priority than
some cases of conversion,like seeing if Plone would make a good cms for
LDP and how to implment it?  
> 
> So, functionally speaking, I'd suggest that no format is an automatic
> deal-breaker, and it's not in LDP's interest to so suggest.

It depends on whether or not the doc can be easily converted to html or plain
text.  LDP has priorities.  For example the publisher O'Reilly offered us
the 2nd edition of its Network book and there was no one on the discuss
list to accept it.  David Merrill's work on a CMS data base using Plone
for LDP went to waste since no one took over when he dropped out due to
serious illness (aids).  And what about maintaining our website (and
mirrors)?  And recruiting new people?  

If it's going to take any significant amount of time to convert to other
formats, I think we can only accept it if someone can be found to convert
it.  Of course, the effort to devote to such conversions depends on the
quality of the doc and the need for it.  We need to have a list of formats
that we can convert automatically (and perhaps another list of formats we
can easily convert but not fully automatically).  In some cases we would
need to let the author know that we just don't have the resources to do
the conversion.  

In some cases people have taken over an out-of-date HOWTO in linuxdoc and
converted it to docbook.  And I worry that LDP may have destroyed the
linuxdoc version.  Are the old version from cvs all in git-hub?  There are
many cases where a HOWTO is taken over by a new author and in that case
the new author wants the doc to be in a format that is easy for him/her to
deal with.
			David Lawyer

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

> LDP would simply tell authors to put their name, the date, etc. at the
> start of the doc, or it would be provided by a template (like for emails
> or for the how-to generator that's still on the web).  Why would someone
> refuse to do that?  It's so easy to do.

Dunno.  It was _your_ hypothetical.

My only point is that it was pretty easily fixed by a quick query to the
author, ergo would immediately thereafter lead to a document to which
LDP had no objection on such grounds.

> What about volunteering to do something that has a higher priority than
> some cases of conversion,like seeing if Plone would make a good cms for
> LDP and how to implment it?  

I was intending to avoid expressing my personal views about Plone, as I
would rather accentuate the positive.  I've had professional experience
with that CMS in the 2000s.

(I can dig up what I said about it, as it was colourful and most people
found it amusing at the time.  And also provably true.)


> > So, functionally speaking, I'd suggest that no format is an automatic
> > deal-breaker, and it's not in LDP's interest to so suggest.
> 
> It depends on whether or not the doc can be easily converted to html or plain
> text.

I merely addressed what you said, as you stated it.  Possibly you didn't
mean to imply it should be a deal-breaker.  But great!  The matter is 
clarified.

In my experience, facts on the ground trump theory.  E.g., if someone
submits a doc to LDP he/she wrote in WordPerfect 8.1 for Linux and I
happen to pick it up for review, that would be dumb luck as I happen to
have a working copy of that antique 1990s IA32 program around, and I
would be willing to turn it into something more useful.  Some other
reviewer would probably say 'Gosh, can't deal with this.  Could you
resubmit in a format from this millennium?'  In this sense, discussing
what are the limits of what formats LDP is willing to accept is a
fruitless discussion:  LDP will accept what the relevant LDP staff can
and will deal with.


> LDP has priorities.

I have priorities.  You have priorities.  I'm not sure what the claim
that 'LDP has priorities' even means, let alone what that has to do with
me.  (Sometimes when people advise me about what _my_ priorities are, I
recount my story in the Linux User Group HOWTO about my friend and
assistant editor Ed.
http://en.tldp.org/HOWTO/User-Group-HOWTO-7.html#ss7.4 )


> If it's going to take any significant amount of time to convert to
> other formats, I think we can only accept it if someone can be found
> to convert it.

Enfin, you are angling towards where I was.  Great!  Once again, the
matter is clarified.


> We need to have a list of formats that we can convert automatically
> (and perhaps another list of formats we can easily convert but not
> fully automatically). 

If you think this is important, you're welcome to create one.
Personally, I'd just write to the author and say 'Gee, I'm not sure I
can handle [foo].  Got anything else?'