On Mon, 18 Oct 2010 14:46:13 -0400, Gour D. <gour@atmarama.net> wrote:

> On Mon, 18 Oct 2010 11:14:54 -0700
>>>>>>> "Walter" == Walter Bright <newshound2@digitalmars.com> wrote:
>
> Walter> I think this would be great to include in the D distribution,
> Walter> with a web page with step-by-step instructions.
>
> May I ask here whether Ddoc is recommended way to document D code over
> e.g. Doxygen etc.?
>
> I'm starting and would like to adopt proper tools...

doxygen had minimal support for D1, but it has not been updated in a long long time.

Besides ddoc, there are a couple of D-based doc generators: descent (which I guess is dead), and dil.

However, all the d-based tools parse the same ddoc style, so no matter what tool you use, you should use ddoc to document your code.

-Steve

On Mon, 18 Oct 2010 14:57:13 -0400
>>>>>> "Steven" == "Steven Schveighoffer" <schveiguy@yahoo.com> wrote:

Steven> However, all the d-based tools parse the same ddoc style, so no Steven> matter what tool you use, you should use ddoc to document your Steven> code.

Thanks a lot. That's what I needed to hear. ;)


Sincerely,
Gour

-- 

Gour  | Hlapicina, Croatia  | GPG key: CDBF17CA
----------------------------------------------------------------

Walter Bright wrote:

> Alix Pexton wrote:
>> After a lot of thought, I have come to the conclusion that giving DDoc the power required to calculate layout in a way that is general enough to be used not only by PDF but by any other layout technology, and the ability to work with a flattened tree, is a non starter.
> 
> Perhaps you're right. But it strikes me as possible that a Ddoc template that emits the text in some custom format, which is then read by a custom pdf generator program, could work. In other words, a two step process.

ddoc -> LaTeX -> profit

LaTeX produces most beautiful output, including (amongst others) well rendered pdf. No need to write a custom generator.

Andrei Alexandrescu wrote:

> On 10/18/2010 06:54 AM, Alix Pexton wrote:
>> On 17/10/2010 18:45, Walter Bright wrote:
>>> Apparently, it is fairly simple to convert plain text files to PDF.
>>>
>>> http://re-factor.blogspot.com/2010/10/text-to-pdf.html
>>>
>>> Which suggests to me it should be equally simple to create a Ddoc macro file to allow Ddoc to emit pdf files directly.
>>>
>>> Anyone want a nice weekend project to product this?
>>
>> I read the PDF spec once*, I can see in my mind what a PDF generated by DDoc could look like, and I'm quite confident in saying that it is nothing like as pretty or simple to produce as the current, most basic HTML output.
> 
> There's no need for all that. It took me a short time to produce a set of macros that would generate LaTeX files from ddoc. I'm sure I have it somewhere, or I could rewrite it. From there you get to produce high quality PDFs.
> 
> Andrei

Cool, it would be nice if you could find it. I have a D class for program listings (for a presentation with beamer), needs a little work but could be useful too.

Hello Alix,

> Doing a layout for an unstructured stream of text in a fixed width
> typeface (such as in the link you posted) is quite simple, but - as
> far as I can fathom - is still beyond the current DDoc. Using variable
> width typefaces, indentation, borders, emphasis, etc. to try and
> produce a PDF with the same visual style as that which can be easily
> achieved using the current HTML macros would be very difficult (though
> I'm not going to go so far as saying its impossible).

IIRC pdf is built on PS and PS is Turing compleat, you might be able to do all the processing in PS and just slap the DDoc content is as data.

-- 
... <IXOYE><

Andrei Alexandrescu wrote:
> There's no need for all that. It took me a short time to produce a set of macros that would generate LaTeX files from ddoc. I'm sure I have it somewhere, or I could rewrite it. From there you get to produce high quality PDFs.

I think you're right and that's the way we should do it.

On the other hand, just for fun I wanted to see if I could read a paperback I got from the thrift store on my ipod. I sliced the back off, and ran it through a scanner to create an OCR'd pdf. Loading the pdf into my ipod didn't work, as it was 25 megs and so far, the only way I've figured out how to get pdf's to the ipod is via email.

Trying a small sample did work, but the page image on the ipod was just too small to read. I had to use a magnifying glass.

So I loaded the pdf, did a select all, and wrote the text out to a simple text file. Emailing the text file worked, but imail has a crappy text file reader. No good.

Next I downloaded and compiled the text2pdf.c file. Trying it crashed. Buffer overflow!! Bumped all the buffer sizes way up, and it worked. Emailed it to the ipod, saved it as an "ibook", and I could read it.

The pages were still too big, though, and the ibook reader made zooming the pages a miserable experience. (Apple didn't get everything right.)

I downloaded the pdf spec and figured out how to set the page margins to zilch (don't need page margins on the ipod), about 11 lines by 60 characters seems to work fine. Reset the font to Times-Roman. Now it works perfectly!

The only problem is the book itself sux. Oh well!

"Walter Bright" <newshound2@digitalmars.com> wrote in message news:i9j7c7$209t$1@digitalmars.com...
> Andrei Alexandrescu wrote:
>> There's no need for all that. It took me a short time to produce a set of macros that would generate LaTeX files from ddoc. I'm sure I have it somewhere, or I could rewrite it. From there you get to produce high quality PDFs.
>
> I think you're right and that's the way we should do it.
>
> On the other hand, just for fun I wanted to see if I could read a paperback I got from the thrift store on my ipod. I sliced the back off, and ran it through a scanner to create an OCR'd pdf. Loading the pdf into my ipod didn't work, as it was 25 megs and so far, the only way I've figured out how to get pdf's to the ipod is via email.
>

My portable music player is a Toshiba Gigabeat F with the Rockbox firmware. I can put any files I want onto it by connecting the USB cord and treating it like the USB HDD that it actually is. (Doesn't have a pdf reader though. Although it can display text files.)

> (Apple didn't get everything right.)
>

Clearly not!

 Il 18/10/10 20.13, Walter Bright ha scritto:
> Perhaps you're right. But it strikes me as possible that a Ddoc template that emits the text in some custom format, which is then read by a custom pdf generator program, could work. In other words, a two step process.
IMHO Custom text format >> LaTeX

On 19/10/2010 04:12, BCS wrote:
> Hello Alix,
>
>> Doing a layout for an unstructured stream of text in a fixed width
>> typeface (such as in the link you posted) is quite simple, but - as
>> far as I can fathom - is still beyond the current DDoc. Using variable
>> width typefaces, indentation, borders, emphasis, etc. to try and
>> produce a PDF with the same visual style as that which can be easily
>> achieved using the current HTML macros would be very difficult (though
>> I'm not going to go so far as saying its impossible).
>
> IIRC pdf is built on PS and PS is Turing compleat, you might be able to
> do all the processing in PS and just slap the DDoc content is as data.
>

Hmn, I hadn't thought of that, I looked it up, and it seems that the subset of PS in the PDF spec is crippled, it has no "if" or "loop" constructs...

But you reminded me that PDFs can embed ActionScript! I'm not sure how practical it would be, particularly for large documents, as the whole stream would need to be processed in order to view any page, or even calculate the number of pages. PDF was designed so that any page could be reached and rendered quickly without having to process all the pages that came before.

Overall, I think the LaTeX in the middle solution is a far better option, especially as it is already working ^^

A...

On 10/18/10 9:37 PM, Walter Bright wrote:
> On the other hand, just for fun I wanted to see if I could read a
> paperback I got from the thrift store on my ipod. I sliced the back off,
> and ran it through a scanner to create an OCR'd pdf. Loading the pdf
> into my ipod didn't work, as it was 25 megs and so far, the only way
> I've figured out how to get pdf's to the ipod is via email.

Apple has been notorious for making it hard to load files onto their iOS devices.  Recently in iOS 4 they've provided for it through iTunes, but it's still very clunky.  For PDFs I use GoodReader which makes it somewhat easy to load files wirelessly and whose claim to fame is that it supports very large PDFs without crashing.