Re: html to man page

[Tim via users]

Allegedly, on or about 5 April 2018, Sam Varshavchik sent:
> This is not Docbook XML.

I know that.  I was using an example of something in HTML (forgetting
to mention that), that's simple to read, but often gets mangled when
translating between different mark-up languages.  Convert back and
forth, and that simple bit of writing turns into a convoluted block of
unnecessary gumph.

-- 
[tim@localhost ~]$ uname -rsvp
Linux 4.15.10-200.fc26.x86_64 #1 SMP Thu Mar 15 17:14:41 UTC 2018 x86_64

Boilerplate:  All mail to my mailbox is automatically deleted.
There is no point trying to privately email me, I only get to see
the messages posted to the mailing list.

Well somebody had to eat the last biscuit.
You're just miffed that it wasn't you.
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Sam Varshavchik]

Tim via users writes:


I'm pretty sure I've looked at Docbook, though could have been another
thing.  But what I found when using *some* form of intermediate
language, that the conversions to other forms were not optimal.

I might write a page with headings and subheadings, properly in
sequence, and text between.

Like:

   Pancakes

  


This is not Docbook XML.




pgpqBCWFKsnqn.pgp
Description: PGP signature
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[JD]

On 04/05/2018 08:29 AM, Tim via users wrote:

Allegedly, on or about 4 April 2018, Sam Varshavchik sent:

I find Docbook XML to be irreplacable, when it comes to writing
technical documentation that serves as a single source of both manual
pages and publishable HTML.

I'm pretty sure I've looked at Docbook, though could have been another
thing.  But what I found when using *some* form of intermediate
language, that the conversions to other forms were not optimal.

I might write a page with headings and subheadings, properly in
sequence, and text between.

Like:

Pancakes

   

Ingredients

  
Flour
Milk
etc...
  

   

   

 Method

And so on, and so forth...

Only to find out the translation has lost the context, converting plain
headings into stylised generic headings all of the same hierarchy.  Or
that straight-forward attributes (name="something") get butchered into
garbage (name="g12").

Or that your two languages have no overlap in being able to do the same
thing, albeit using different methods, and content gets butchered into
inappropriate simulations of what you were trying to do.


Thanks for the heads up!!
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Tim via users]

Allegedly, on or about 4 April 2018, Sam Varshavchik sent:
> I find Docbook XML to be irreplacable, when it comes to writing  
> technical documentation that serves as a single source of both manual
> pages and publishable HTML.

I'm pretty sure I've looked at Docbook, though could have been another
thing.  But what I found when using *some* form of intermediate
language, that the conversions to other forms were not optimal.

I might write a page with headings and subheadings, properly in
sequence, and text between.

Like:

   Pancakes

  

   Ingredients

 
   Flour
   Milk
   etc...
 

  

  

Method

And so on, and so forth...

Only to find out the translation has lost the context, converting plain
headings into stylised generic headings all of the same hierarchy.  Or
that straight-forward attributes (name="something") get butchered into
garbage (name="g12").

Or that your two languages have no overlap in being able to do the same
thing, albeit using different methods, and content gets butchered into
inappropriate simulations of what you were trying to do.

-- 
[tim@localhost ~]$ uname -rsvp
Linux 4.15.10-200.fc26.x86_64 #1 SMP Thu Mar 15 17:14:41 UTC 2018 x86_64

Boilerplate:  All mail to my mailbox is automatically deleted.
There is no point trying to privately email me, I only get to see
the messages posted to the mailing list.

Linux cures Windows pains.
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Andras Simon]

2018-04-05 0:29 GMT+02:00, Sam Varshavchik :
> Andras Simon writes:
[...]
>> I can't resist recommending the late Erik Naggum's xml rant (one of
>> many):
>>
>> https://www.schnada.de/grapt/eriknaggum-xmlrant.html
>>
>> To whet your appetite, here's a short excerpt:
>>
>> "In many ways, the current American presidency and XML have much in
>> common.  Both have clear lineages back to very intelligent people.
>> Both demonstrate what happens when you give retards the tools of the
>> intelligent."
>
> I will agree with this, in some specific circumstances. For example: this is
>
> a perfect explanation for SOAP and WSDL.
>
> But, I find Docbook XML to be irreplacable, when it comes to writing
> technical documentation that serves as a single source of both manual pages
>
> and publishable HTML. And, it's infinitely hackable. Like I mentioned, with
>
> some hacking I can now easily embed links from my Docbook-based tutorials to
>
> Doxygen-generated C++ class documentation.


Then you should also read Erik Naggum's C++ rants.


But of course, most of us should stick to the tools we're comfortable
(or are required to work) with.
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Sam Varshavchik]

Andras Simon writes:


2018-04-04 13:53 GMT+02:00, Tim via users :
> Allegedly, on or about 2 April 2018, Cameron Simpson sent:
>> I have to say I've very -1 on anything that uses XML as a source
>> format for human written content. It is massively hostile to
>> authoring by hand.
>
> As I recall, it's meant to be human understandable (and editable with a
> plain text editor), but meant to be using XML editing software for
> actually creating it.

I can't resist recommending the late Erik Naggum's xml rant (one of many):

https://www.schnada.de/grapt/eriknaggum-xmlrant.html

To whet your appetite, here's a short excerpt:

"In many ways, the current American presidency and XML have much in
common.  Both have clear lineages back to very intelligent people.
Both demonstrate what happens when you give retards the tools of the
intelligent."


I will agree with this, in some specific circumstances. For example: this is  
a perfect explanation for SOAP and WSDL.


But, I find Docbook XML to be irreplacable, when it comes to writing  
technical documentation that serves as a single source of both manual pages  
and publishable HTML. And, it's infinitely hackable. Like I mentioned, with  
some hacking I can now easily embed links from my Docbook-based tutorials to  
Doxygen-generated C++ class documentation.




pgp2nSGxPBoOc.pgp
Description: PGP signature
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Bob Marcan]

...
> I can't resist recommending the late Erik Naggum's xml rant (one of many):
> 
> https://www.schnada.de/grapt/eriknaggum-xmlrant.html
> 
> To whet your appetite, here's a short excerpt:
> 
> "In many ways, the current American presidency and XML have much in
> common.  Both have clear lineages back to very intelligent people.
> Both demonstrate what happens when you give retards the tools of the
> intelligent."
> 
> And he wasn't even talking about Trump.
...
+1
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Andras Simon]

2018-04-04 13:53 GMT+02:00, Tim via users :
> Allegedly, on or about 2 April 2018, Cameron Simpson sent:
>> I have to say I've very -1 on anything that uses XML as a source
>> format for human written content. It is massively hostile to
>> authoring by hand.
>
> As I recall, it's meant to be human understandable (and editable with a
> plain text editor), but meant to be using XML editing software for
> actually creating it.

I can't resist recommending the late Erik Naggum's xml rant (one of many):

https://www.schnada.de/grapt/eriknaggum-xmlrant.html

To whet your appetite, here's a short excerpt:

"In many ways, the current American presidency and XML have much in
common.  Both have clear lineages back to very intelligent people.
Both demonstrate what happens when you give retards the tools of the
intelligent."

And he wasn't even talking about Trump.
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Tim via users]

Allegedly, on or about 2 April 2018, Cameron Simpson sent:
> I have to say I've very -1 on anything that uses XML as a source
> format for human written content. It is massively hostile to
> authoring by hand.

As I recall, it's meant to be human understandable (and editable with a
plain text editor), but meant to be using XML editing software for
actually creating it.

-- 
[tim@localhost ~]$ uname -rsvp
Linux 4.15.10-200.fc26.x86_64 #1 SMP Thu Mar 15 17:14:41 UTC 2018 x86_64

Boilerplate:  All mail to my mailbox is automatically deleted.
There is no point trying to privately email me, I only get to see
the messages posted to the mailing list.

Windows, it's enough to make a grown man cry!
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Dave Cross]

On 2 April 2018 at 06:29, Sam Varshavchik  wrote:

> Can POD generate an entire web site, with an automatically-generated table
> of contents?

Well, Pod is a mark-up format. So no.

But with tools like Pod::Html (https://metacpan.org/pod/Pod::Html) and
Pod::POM (https://metacpan.org/pod/Pod::POM) it's not particularly
hard to achieve that. That is, after all, the basis of site like
https://metacpan.org/.

I once wrote a whole book in Pod -
http://shop.oreilly.com/product/9780596004767.do

Dave...

-- 
Dave Cross :: d...@dave.org.uk
http://dave.org.uk/
@davorg
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Dave Cross]

On 1 April 2018 at 18:56, JD  wrote:
> Hi all,
> I have an app that has no manpage, but has about 170 html files,
> all of which index into a subset of the 168 files.
>
> I would like to use an app that will produce a single manpage like
> text file.
>
> Is there an app that can do this?
>
> I saw a few apps on google search, but none of them are producing what I
> want.

Have you looked at Pandoc (http://pandoc.org/)? It will definitely
read HTML and write groff (the format that man pages use).

I'd recommend using Pandoc to convert your HTML to Markdown and using
that as your source - generating other formats from that.

You might need to do quite a lot of manual clean-up of the Markdown
files though. But you'd only need to do it once.

Dave...

-- 
Dave Cross :: d...@dave.org.uk
http://dave.org.uk/
@davorg
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Cameron Simpson]

On 02Apr2018 01:29, sam varshavchik  wrote:

Cameron Simpson writes:
Well I was using Perl's POD format several years ago as my primary manual 
writing syntax, generates man and html. Good HTML to XHTML might be an easy 
transcription, I've not tried.


Not specificly recommending POD, it was just a good syntax for the 
time. Quite low in features, but in many cases that is a good thing.


I need to revisit this sometime myself, as I've got a project that 
will need man pages and fuller documentation as well.


Can POD generate an entire web site, with an automatically-generated 
table of contents?


Not really. Like I said, low in features.

The Python people seem to like restructuredtext a lot; there's a tool called 
sphinx for making whole sites from it, which seems liked.


https://www.libcxx.org is just one big Docbook document, with navigation 
footers. Doxygen generates the reference pages. Doxygen produces an XML file 
with an index of all the reference pages. I run a custom XSLT stylesheet to 
translate the index to URLs and entity references, which then gets included 
into the main, paginated tutorial, generates links directly to the reference 
pages.


I'm a big fan of good cross linking.

But my basic point is that authoring syntax for humans needs to be 
light weight so that the source looks a fair bit like ordinary 
prose. Tools can always be written to generate specific outputs.


The more it looks like ordinary prose, the less metadata exists that 
makes it possible to intelligently format it.


Sure, but a lot of prose doesn't need a great deal of special formatting.

I'm not sure we disagree very much here, except for my dislike of syntaxes with 
heaps of punctuation everywhere, and XML falls into that slot for me.


Cheers,
Cameron Simpson 
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Sam Varshavchik]

Cameron Simpson writes:


On 01Apr2018 23:55, sam varshavchik  wrote:

Cameron Simpson writes:
There are plenty of popular human friendly formats out there like markdown  
and restructured text etc which render to various output formats.


Which "human friendly" format can I use which already has tools to generate  
both well-formed XHTML and man-compatible troff content, from the same  
source?


Well I was using Perl's POD format several years ago as my primary manual  
writing syntax, generates man and html. Good HTML to XHTML might be an easy  
transcription, I've not tried.


Not specificly recommending POD, it was just a good syntax for the time.  
Quite low in features, but in many cases that is a good thing.


I need to revisit this sometime myself, as I've got a project that will need  
man pages and fuller documentation as well.


Can POD generate an entire web site, with an automatically-generated table  
of contents? https://www.libcxx.org is just one big Docbook document, with  
navigation footers. Doxygen generates the reference pages. Doxygen produces  
an XML file with an index of all the reference pages. I run a custom XSLT  
stylesheet to translate the index to URLs and entity references, which then  
gets included into the main, paginated tutorial, generates links directly to  
the reference pages.


But my basic point is that authoring syntax for humans needs to be light  
weight so that the source looks a fair bit like ordinary prose. Tools can  
always be written to generate specific outputs.


The more it looks like ordinary prose, the less metadata exists that makes  
it possible to intelligently format it.




pgp42FikqjOxE.pgp
Description: PGP signature
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Cameron Simpson]

On 01Apr2018 23:55, sam varshavchik  wrote:

Cameron Simpson writes:
There are plenty of popular human friendly formats out there like markdown 
and restructured text etc which render to various output formats.


Which "human friendly" format can I use which already has tools to 
generate both well-formed XHTML and man-compatible troff content, from the 
same source?


Well I was using Perl's POD format several years ago as my primary manual 
writing syntax, generates man and html. Good HTML to XHTML might be an easy 
transcription, I've not tried.


Not specificly recommending POD, it was just a good syntax for the time. Quite 
low in features, but in many cases that is a good thing.


I need to revisit this sometime myself, as I've got a project that will need 
man pages and fuller documentation as well.


But my basic point is that authoring syntax for humans needs to be light weight 
so that the source looks a fair bit like ordinary prose. Tools can always be 
written to generate specific outputs.


Cheers,
Cameron Simpson 
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Sam Varshavchik]

Cameron Simpson writes:


On 01Apr2018 18:19, sam varshavchik  wrote:

If this is your app and your documentation, I suggest you spend the time  
converting your app's documentation to Docbook XML, and then use docbook  
tools to generate both HTML and man page documentation from your docbook  
sources.


I have to say I've very -1 on anything that uses XML as a source format for  
human written content. It is massively hostile to authoring by hand.


I had that reaction at first, but with Docbook XML, and the associated  
tools, I find it very easy to generate both web-ready content, and the  
associated man pages.


Plus I have a rich library of non-Docbook generic XML tools, like XSLT  
processors that lets me do things like insert Good Adword banner HTML  
boilerplate, into my generated content – working seamlessly with Docbook  
XML.


There are plenty of popular human friendly formats out there like markdown  
and restructured text etc which render to various output formats.


Which "human friendly" format can I use which already has tools to generate  
both well-formed XHTML and man-compatible troff content, from the same  
source?





pgpQ59upoXvM4.pgp
Description: PGP signature
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Dave Ihnat]

On Mon, Apr 02, 2018 at 09:54:27AM +1000, Cameron Simpson wrote:
> I have to say I've very -1 on anything that uses XML as a source
> format for human written content. It is massively hostile to
> authoring by hand.

Yes.

> Prehistoric it is not. Old yes, showing its age yes. But prehistoric
> is flat out incorrect.

The nice thing is I have a shellscript from the '80s when I was at BTL
Naperville (and rather a 'ROFF nerd) that still works nicely to generate a
man file.  It works, and has outlived other doc formats that have not
caught on (such as info).

Cheers,
--
Dave Ihnat
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Cameron Simpson]

On 01Apr2018 18:19, sam varshavchik  wrote:

JD writes:

I have an app that has no manpage, but has about 170 html files,
all of which index into a subset of the 168 files.
I would like to use an app that will produce a single manpage like
text file.
Is there an app that can do this?


I don't know of one. You might need to roll your own. If this is a one off task 
then you can get away with various hacks that a general purpose solution 
wouldn't tolerate.


If this is your app and your documentation, I suggest you spend the time 
converting your app's documentation to Docbook XML, and then use docbook tools 
to generate both HTML and man page documentation from your docbook sources.


I have to say I've very -1 on anything that uses XML as a source format for 
human written content. It is massively hostile to authoring by hand.


There are plenty of popular human friendly formats out there like markdown and 
restructured text etc which render to various output formats.


'roff deserves an honorable retirement. It served us well, but the technology 
is more than just obsolete, it's prehistoric.


Prehistoric it is not. Old yes, showing its age yes. But prehistoric is flat 
out incorrect.


Cheers,
Cameron Simpson 
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org

Re: html to man page

[Sam Varshavchik]

JD writes:


Hi all,
I have an app that has no manpage, but has about 170 html files,
all of which index into a subset of the 168 files.

I would like to use an app that will produce a single manpage like
text file.

Is there an app that can do this?

I saw a few apps on google search, but none of them are producing what I  
want.


If this is your app and your documentation, I suggest you spend the time  
converting your app's documentation to Docbook XML, and then use docbook  
tools to generate both HTML and man page documentation from your docbook  
sources.


That's going to be a major time sink; but is definitely the way to go.

I think that converting Linux man pages to Docbook XML is long overdue.  
'roff deserves an honorable retirement. It served us well, but the  
technology is more than just obsolete, it's prehistoric.


I broached this topic with Michael Kerrisk some years ago, and I even wrote  
a tool that converted all Linux man pages to Docbook XML (see  
http://manpages.courier-mta.org) – but he wasn't interested. Oh well.


pgp_ctZyajpGa.pgp
Description: PGP signature
___
users mailing list -- users@lists.fedoraproject.org
To unsubscribe send an email to users-le...@lists.fedoraproject.org