Re: [PHPTAL] Any updates to translation tools?

[Christoph Frick]

On Tue, Aug 23, 2011 at 01:36:27PM -0700, Darrell Hamilton wrote:

As for RST vs Markdown in general: I would assume, that their
differences are minor and are of the YMMV kind.  I would consider any
developer being able to adopt fast.

> Pandoc does have some optional Markdown extensions for dealing with
> inline code and syntax highlighting.  Aside from seeing the syntax, I
> have not played around with it yet.

Sphinx does this too on top of RST - yet its focus is on python and
C(++) -- maybe this is to consider, when doing lots of PHP centric
stuff.  Adding (PHP)TAL syntax highlighting on top of the XML/HTML-Code
of the framework has to be done by hand in any way.

> Unless someone else has input on the capabilities of RST to break down a
> single document into parts, I'll start investigating that next.

For a "single-page" version?  My "single-page" is the PDF and the EPUB
here.  So no experience there on my end.

With Sphinx you just build a directory structure of your liking and then
build a TOC in the pages to link them.  do a ``make'' and you are good
to go.  Changing style is very easy and there are a few themes to start
with already in the base distribution.  Search is done by Javascript and
works reasonably well.

A tool bootstrap you into something to start with and then you write
on.  The tools asks some basic stuff which nearly all of it can be
adjusted in a config file and the rest in the Makefile.  For PDF/EPUB
you just define (optionally) another "start"-page and generate from
there.

-- 
cu


pgpv6gEdmZ8r1.pgp
Description: PGP signature
___
PHPTAL mailing list
PHPTAL@lists.motion-twin.com
http://lists.motion-twin.com/mailman/listinfo/phptal

Re: [PHPTAL] Any updates to translation tools?

[Darrell Hamilton]

I installed pandoc via apt on an Ubuntu Server installation (don't recall if
it's 10 or 11) without any trouble.  Pandoc does have some optional Markdown
extensions for dealing with inline code and syntax highlighting.  Aside from
seeing the syntax, I have not played around with it yet.

Unless someone else has input on the capabilities of RST to break down a
single document into parts, I'll start investigating that next.

Darrell Hamilton,
Software Developer,
4over, Inc
darre...@4over.com
818-246-1170 ext. 285


2011/8/23 Kornel Lesiński 

> On Tue, 23 Aug 2011 06:15:57 +0100, Darrell Hamilton 
> wrote:
>
>  Does anyone have any additional input on this point?  From what I've
>> gathered, pandoc is what you want if your converting between any number of
>> markup languages.  It can convert to DocBook, RST, Markdown, and many
>> others.  Unfortunately, it does not take DocBook as an input format.
>>
>
> pandoc is difficult to install for me. Did you get it working?
>
> DocBook -> HTML -> Markdown might work?
>
>
>  Based on the links provided by Christoph, there are some tools for
>> converting DocBook to RST, but they appear to be in their infancy.  I have
>> not experimented with them yet.
>>
>> As a broader question, is Markdown the preferred format?  Or is the format
>> open to general discussion?  I do not have a preference at this time nor do
>> I know enough of the pros/cons of each to say anything about which is the
>> better tool for the job, but it might be worth hearing from people who
>> have more experience with them.
>>
>
> I have slight preference for Markdown, since it uses single backtick for
> inline code. reStructuredText is fine though.
>
> The next step would be to look into tool that produces multipage
> documentation from the single source file. I don't know of any for Markdown,
> so if reStructuredText has good (post)processors, it might be better.
> Otherwise, I'll probably write something myself.
>
> --
> regards, Kornel Lesiński
>
>
> __**_
> PHPTAL mailing list
> PHPTAL@lists.motion-twin.com
> http://lists.motion-twin.com/**mailman/listinfo/phptal
>
___
PHPTAL mailing list
PHPTAL@lists.motion-twin.com
http://lists.motion-twin.com/mailman/listinfo/phptal

Re: [PHPTAL] Any updates to translation tools?

[Kornel Lesiński]

On Tue, 23 Aug 2011 06:15:57 +0100, Darrell Hamilton   
wrote:



Does anyone have any additional input on this point?  From what I've
gathered, pandoc is what you want if your converting between any number  
of markup languages.  It can convert to DocBook, RST, Markdown, and many

others.  Unfortunately, it does not take DocBook as an input format.


pandoc is difficult to install for me. Did you get it working?

DocBook -> HTML -> Markdown might work?


Based on the links provided by Christoph, there are some tools for
converting DocBook to RST, but they appear to be in their infancy.  I  
have not experimented with them yet.


As a broader question, is Markdown the preferred format?  Or is the  
format open to general discussion?  I do not have a preference at this  
time nor do I know enough of the pros/cons of each to say anything about  
which is the
better tool for the job, but it might be worth hearing from people who  
have more experience with them.


I have slight preference for Markdown, since it uses single backtick for  
inline code. reStructuredText is fine though.


The next step would be to look into tool that produces multipage  
documentation from the single source file. I don't know of any for  
Markdown, so if reStructuredText has good (post)processors, it might be  
better. Otherwise, I'll probably write something myself.


--
regards, Kornel Lesiński

___
PHPTAL mailing list
PHPTAL@lists.motion-twin.com
http://lists.motion-twin.com/mailman/listinfo/phptal

Re: [PHPTAL] Any updates to translation tools?

[Darrell Hamilton]

Does anyone have any additional input on this point?  From what I've
gathered, pandoc is what you want if your converting between any number of
markup languages.  It can convert to DocBook, RST, Markdown, and many
others.  Unfortunately, it does not take DocBook as an input format.

Based on the links provided by Christoph, there are some tools for
converting DocBook to RST, but they appear to be in their infancy.  I have
not experimented with them yet.

As a broader question, is Markdown the preferred format?  Or is the format
open to general discussion?  I do not have a preference at this time nor do
I know enough of the pros/cons of each to say anything about which is the
better tool for the job, but it might be worth hearing from people who have
more experience with them.

Darrell Hamilton,
Software Developer,
4over, Inc
darre...@4over.com
818-246-1170 ext. 285


On Mon, Aug 22, 2011 at 2:47 AM, Christoph Frick wrote:

> On Fri, Aug 19, 2011 at 11:37:16PM -0700, Darrell Hamilton wrote:
>
> > As for HTML to Markdown, Pandoc, http://johnmacfarlane.net/pandoc/ ,
> seems
> > to be the de facto standard so I'm going to start off with that one.
>
> i have recently switched a restructured text doku wiki over to Sphinx
> [1].  there is also a converter from DB to RST suggested by them [2] --
> but i don't know nothing about the quality.
>
> [1] http://sphinx.pocoo.org/index.html
>
> [2] http://code.google.com/p/db2rst/
>
> --
> cu
>
> ___
> PHPTAL mailing list
> PHPTAL@lists.motion-twin.com
> http://lists.motion-twin.com/mailman/listinfo/phptal
>
>
___
PHPTAL mailing list
PHPTAL@lists.motion-twin.com
http://lists.motion-twin.com/mailman/listinfo/phptal

Re: [PHPTAL] Any updates to translation tools?

[Christoph Frick]

On Fri, Aug 19, 2011 at 11:37:16PM -0700, Darrell Hamilton wrote:

> As for HTML to Markdown, Pandoc, http://johnmacfarlane.net/pandoc/ , seems
> to be the de facto standard so I'm going to start off with that one.

i have recently switched a restructured text doku wiki over to Sphinx
[1].  there is also a converter from DB to RST suggested by them [2] --
but i don't know nothing about the quality.

[1] http://sphinx.pocoo.org/index.html

[2] http://code.google.com/p/db2rst/

-- 
cu


pgpQtMZcfK7O9.pgp
Description: PGP signature
___
PHPTAL mailing list
PHPTAL@lists.motion-twin.com
http://lists.motion-twin.com/mailman/listinfo/phptal

Re: [PHPTAL] Any updates to translation tools?

[Darrell Hamilton]

Quick update:

Unfortunately, I'm not having much luck in the direct DocBook to Markdown
search.  Most of what I'm getting out of google are similar conversation
without answers, and conversations on this mailing list back in 2010.

As for HTML to Markdown, Pandoc, http://johnmacfarlane.net/pandoc/ , seems
to be the de facto standard so I'm going to start off with that one.

Darrell Hamilton,
Software Developer,
4over, Inc
darre...@4over.com
818-246-1170 ext. 285


2011/8/19 Kornel Lesiński 

> On Fri, 19 Aug 2011 22:43:36 +0100, Darrell Hamilton 
> wrote:
>
>  On the "Convert DocBook to Markdown" item, there seems to be at least a
>> handful of tools that can convert from HTML to Markdown.  I'll see about
>> putting aside some time to play with a few to figure out if there is a
>> "better" or "best" option among them and, seeing if there is something
>> that can go directly from DocBook to Markdown without the extra step.
>>
>
> Thanks.
>
>
>  Are there any additional requirements, beyond just being able to convert?
>> Is this going to be a one time thing?  (I assume 'yes')  Does it need to
>> be scriptable? (again, I assume 'yes')
>>
>
> Yes, one-time thing. Notes and warnings need to be preserved (I suppose
> Markdown doesn't have anything better than inline HTML for this).
>
> --
> regards, Kornel Lesiński
>
>
> __**_
> PHPTAL mailing list
> PHPTAL@lists.motion-twin.com
> http://lists.motion-twin.com/**mailman/listinfo/phptal
>
___
PHPTAL mailing list
PHPTAL@lists.motion-twin.com
http://lists.motion-twin.com/mailman/listinfo/phptal

Re: [PHPTAL] Any updates to translation tools?

[Kornel Lesiński]

On Fri, 19 Aug 2011 22:43:36 +0100, Darrell Hamilton   
wrote:



On the "Convert DocBook to Markdown" item, there seems to be at least a
handful of tools that can convert from HTML to Markdown.  I'll see about
putting aside some time to play with a few to figure out if there is a
"better" or "best" option among them and, seeing if there is something  
that can go directly from DocBook to Markdown without the extra step.


Thanks.


Are there any additional requirements, beyond just being able to convert?
Is this going to be a one time thing?  (I assume 'yes')  Does it need to  
be scriptable? (again, I assume 'yes')


Yes, one-time thing. Notes and warnings need to be preserved (I suppose  
Markdown doesn't have anything better than inline HTML for this).


--
regards, Kornel Lesiński

___
PHPTAL mailing list
PHPTAL@lists.motion-twin.com
http://lists.motion-twin.com/mailman/listinfo/phptal

Re: [PHPTAL] Any updates to translation tools?

[Darrell Hamilton]

On the "Convert DocBook to Markdown" item, there seems to be at least a
handful of tools that can convert from HTML to Markdown.  I'll see about
putting aside some time to play with a few to figure out if there is a
"better" or "best" option among them and, seeing if there is something that
can go directly from DocBook to Markdown without the extra step.

Are there any additional requirements, beyond just being able to convert?
Is this going to be a one time thing?  (I assume 'yes')  Does it need to be
scriptable? (again, I assume 'yes')

Darrell Hamilton,
Software Developer,
4over, Inc
darre...@4over.com
818-246-1170 ext. 285


2011/8/19 Kornel Lesiński 

> On Sat, 06 Aug 2011 17:07:05 +0100, Anton Andriyevskyy 
> wrote:
>
> (sorry for late reply, I've originally sent that e-mail from wrong
> account!)
>
>
>  I still want to help and finish translation of phptal documentation to
>> russian language (previously started and done 40% of chapters or so).
>>
>> I see php introduced very good online tool to do such things:
>> https://edit.php.net/
>>
>> If it is opensourced, maybe you can setup it so we all can help to
>> translate phptal documentation?
>>
>
> PHP's tool looks like a quite complex beast. I think DocBook is too
> complex to maintain already, and instead of piling more tools to deal with
> it, I'd rather get rid of DocBook and switch to something simpler, e.g.
> Markdown.
>
> To do this, I need:
>
> * tool to convert DocBook to Markdown (or HTML to Markdown):
> https://svn.motion-twin.com/**phptal/trunk/doc/en/book.xml
>
> * tool to generate multi-page HTML with code syntax highlights from
> Markdown (existing scripts might be reusable:
> https://svn.motion-twin.com/**phptal/website/highlight.php
> )
>
> Any volunteers?
>
> --
> regards, Kornel
>
> __**_
> PHPTAL mailing list
> PHPTAL@lists.motion-twin.com
> http://lists.motion-twin.com/**mailman/listinfo/phptal
>
___
PHPTAL mailing list
PHPTAL@lists.motion-twin.com
http://lists.motion-twin.com/mailman/listinfo/phptal

Re: [PHPTAL] Any updates to translation tools?

[Kornel Lesiński]

On Sat, 06 Aug 2011 17:07:05 +0100, Anton Andriyevskyy  
 wrote:


(sorry for late reply, I've originally sent that e-mail from wrong  
account!)



I still want to help and finish translation of phptal documentation to
russian language (previously started and done 40% of chapters or so).

I see php introduced very good online tool to do such things:
https://edit.php.net/

If it is opensourced, maybe you can setup it so we all can help to  
translate phptal documentation?


PHP's tool looks like a quite complex beast. I think DocBook is too
complex to maintain already, and instead of piling more tools to deal with
it, I'd rather get rid of DocBook and switch to something simpler, e.g.
Markdown.

To do this, I need:

* tool to convert DocBook to Markdown (or HTML to Markdown):
https://svn.motion-twin.com/phptal/trunk/doc/en/book.xml

* tool to generate multi-page HTML with code syntax highlights from
Markdown (existing scripts might be reusable:
https://svn.motion-twin.com/phptal/website/highlight.php)

Any volunteers?

--
regards, Kornel

___
PHPTAL mailing list
PHPTAL@lists.motion-twin.com
http://lists.motion-twin.com/mailman/listinfo/phptal