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

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

On Wed, Sep 14, 2016 at 6:43 PM, Michalis Kamburelis <
mic...@gm...> wrote:
[...]

> There a couple of questions and features here:)
>

Hehe... :-D


> 1. As for the best way to present the longer example code: the
> @longCode tag makes a long code example look pretty (with colors, bold
> keywords etc.), see http://pasdoc.sipsolutions.net/LongcodeTag . The
> result looks like this:
> http://michalis.ii.uni.wroc.pl/castle-engine-snapshots/
> docs/reference/html/CastleImages.html#AddLoadImageListener
> .
>

Yes, I've used @longCode too ...


> 2. There is no way to include a Pascal source file and make it look
> like a @longCode output, unfortunately. It would be a nice feature,
> but it's just not done yet. Contributions would be welcome, a tag name
> like @includeCode would be consistent with our other tags. It should
> be easy to do:)
>

... but the @includeCode seems a very nice feature, and I'm going to try to
implement that. :-)

( is this link the official PasDoc Github repo?:
https://github.com/michaliskambi/pasdoc )


>   What you can do now is to use @include
> http://pasdoc.sipsolutions.net/IncludeTag to include a description
> from another file. But that another file will have to include
> @longCode tag ... So it will not be a correct (compileable) Pascal
> code, if that is what you need.
>
>   And you cannot use @tags within @longCode, so you cannot circumvent
> this limitation by writing "@longCode(#@include(a.pas)#)".
>
>   Hm, I came up with such hack: You can create a compileable file with
> @longCode inside by using comments:
>
> ------ (paste this as aaa.pas)
> // @longCode(#
> begin
>   Writeln('aaa');
> end.
> // #)
> ------
>
>   And then include it with @include(aaa.pas). So it's close to what
> you need... *but* the resulting documentation will have extra "//"
> characters.
>
>   I'm afraid we should just implement a tag like @includeCode to make
> it really Ok.
>
[...]

I didn't know that possibilities. :-o

Thanks for share it.

3. As for linking to a separate page: this is not possible for now.
>
>   Although we have a support for complete, separate documentation
> pages, it is right now used for introduction / conclusion pages:
> http://pasdoc.sipsolutions.net/IntroductionAndConclusion . An example
> output is inside the PasDoc's own documentation:
> http://pasdoc.sourceforge.net/autodoc/html/index.html . The first page
> "Pasdoc Sources Overview" is a separate page written using our @tags .
>
>   However, it is not yet possible to create arbitrary separate
> documentation pages whenever you want. It's another feature that I
> would accept patches for (like an @includePage tag, that can be used
> anywhere within a description, to create new page and also link to
> it).


Great features.

I'm going to try to implement the @includeCode feature, maybe the
@includePage can be a next step hehe.

--
Silvio Clécio