Re: [Pasdoc-main] What the best way to specify examples?

[silvioprog <sil...@gm...>]

On Thu, Sep 15, 2016 at 12:08 AM, Michalis Kamburelis <
mic...@gm...> wrote:

>  2016-09-15 4:13 GMT+02:00 silvioprog <sil...@gm...>:
> >
> > Done: https://github.com/michaliskambi/pasdoc/pull/2 .
> >
> > Thank you very much!
> >
>
> Thank you for contributing -- perfect, applied!
>

:-)


> I added a simple documentation to
> http://pasdoc.sipsolutions.net/IncludeCodeTag .
>

I took a look at the new documentation, it was clear and understandable. :-)

ASAP we going to do a small update from:

"You can include multiple source code files (place each filename on a
separate line), they will simply be glued together. ... "

to:

"You can include multiple source code files (place each filename on a
separate line), they will simply be glued together separated by horizontal
lines. ... "


> Adding the sLineBreak (and later removing the last sLineBreak) is not
> necessary, so I removed it in a later commit. That is because you are
> "outside" the FormatPascalCode contents, so you're only adding a
> newline to the generated HTML, LaTeX, XML or such. In case of HTML, it
> will be simply ignored. Two files specified for the @includeCode will
> give this HTML output:
>
> --------
> <pre class="longcode"><span class="pascal_keyword">begin</span>
>   Writeln(<span class="pascal_string">'aaa'</span>);
> <span class="pascal_keyword">end</span>.
> </pre>
>
> <p></p>
>
> <pre class="longcode"><span class="pascal_keyword">begin</span>
>   Writeln(<span class="pascal_string">'aaa'</span>);
> <span class="pascal_keyword">end</span>.
> </pre>
> --------
>

Indeed.


> Your sLineBreak was only adding a newline inside the <p></p>, so it
> does not affect the actual look of the document:) To reliably add a
> newline in PasDoc_Gen, you should use a virtual function like
> LineBreak that makes correct output depending on generator ('<br>' in
> HTML and so on). Although in this case, the default paragraph
> separator works Ok.
>
> If needed, you could introduce a virtual function like
> HorizontalSeparator to TDocGenerator, and override it in HTML to
> return '<hr>', and then use it in HandleIncludeCodeTag to visually
> separate the examples by a horizontal line. I'm note sure what looks
> best here, I leave this decision up to you:)


The hr sounds good, I'm going to do it ASAP. :-)

-- 
Silvio Clécio