[Pasdoc-main] [ pasdoc-Feature Requests-1932055 ] more flexible contents structure

[SourceForge.net <no...@so...>]

Feature Requests item #1932055, was opened at 2008-04-02 09:32
Message generated for change (Comment added) made by drdiettrich
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=354213&aid=1932055&group_id=4213

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
Status: Open
Priority: 5
Private: No
Submitted By: Pavel (psut)
Assigned to: Nobody/Anonymous (nobody)
Summary: more flexible contents structure

Initial Comment:
Hi all, thanks for good work. 

I plan to use pasdoc to prepare documentation for large base of pascal sources, and that material would be included in varoius distrubutions of documentation (for internal use, for programmers, for end-users, entire package, separate parts, etc). 

Right now I'm in the need of following:

 * arbitrary nested structure of sections in TOC. Any of them may be either generated (e.g. "Units") or user-defined (e.g. parsed from "mysection.txt"). This structure is expressed in a "project file", and the structure currently hard-coded becomes just a variant of this file. It means, the code reference is just a part of a documentation, there is also would be a theory chapter, tutorial, etc.  

 * Ability to generate explicitly any particular section, from entire project to single method. This is neccessary to provide rapid feedback while editing particular piece of documentation, without the need to build entire docs. Spellchecking fits nice here.

I'm going to dig into pasdoc sources myself and need your suggestions. 

Thank you again for good tool, hope to make it even better. ;)

--Pavel. 

----------------------------------------------------------------------

Comment By: Dr. Diettrich (drdiettrich)
Date: 2008-08-27 06:11

Message:
Logged In: YES 
user_id=477651
Originator: NO

If you are still interested in an implementation of your suggestions: the
redesign in the PasDoc2 branch could allow for kind of a "preview" in the
GUI. You could assist in implementing the editor, which currently still is
read-only, while I would update the (HTML) generator.

----------------------------------------------------------------------

Comment By: Michalis Kamburelis (kambi)
Date: 2008-04-06 21:04

Message:
Logged In: YES 
user_id=987895
Originator: NO

1. As for the "nested structure of sections in TOC": if you mean section
and table of contents within introduction/conclusion
(http://pasdoc.sipsolutions.net/IntroductionAndConclusion) then you can
already nest sections there in any way you like.

If you mean the ability to configure left navigation frame of the HTML
documentation, then point taken --- this could probably be implemented, as
a more general method of specifying any number of introducion/conclusion
pages. For now, is existing mechanism on
http://pasdoc.sipsolutions.net/IntroductionAndConclusion not enough for
you?

If you want to hack the source code for this yourself, just take a look in
the sources how introduction/conclusion is handled. Basically, search
inside trunk/source/component/PasDoc_Gen.pas and some other files for words
"ExternalItem" and "introduction". Then try to change it to more flexible
mechanism.

2. This is not as easy as it seems. Even if you generate documentation for
a single method, you still must know (that is, parsed) everything else in
the project (at least, every unit used by the current unit). This is needed
to generate e.g. proper @links.

You can avoid parsing of the unchanged units by using --cache-dir option
(see http://pasdoc.sipsolutions.net/CacheOption). This makes a great
speedup for larger projects. It's still not instant-fast (it takes some
time to read the cache and expand descriptions from the cache anyway), but
it's quite fast.

For really instant preview (when editing particular part of documentation)
you can just re-run pasdoc on a single unit file. This will make links
wrong (since pasdoc will not know about other units), but everything else
should look Ok. That's how I work with my docs, when I need instant-fast
preview of some particular part of documentation that I'm writing right
now.

The only thing that I see that could be implemented to provide better
instant-like previews is to make a button like "ReParse" in pasdoc_gui. The
idea is to keep parsed tree in memory after you generated your
documentation from pasdoc_gui. If you will not close pasdoc_gui, you can
just click "ReParse" to only re-read and re-expand some particular part of
documentation. This would require some work to implement, but doesn't seem
too hard  --- Richard B. Winston did probably the hardest part of this in
pasdoc_gui some time ago.

If you want to hack this yourself, you can start looking at what tvUnits
can do for you in trunk/source/gui/frmhelpgeneratorunit.pas file. E.g. see
the "demo" that tvUnits works in TfrmHelpGenerator.tvUnitsClick method.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=354213&aid=1932055&group_id=4213