hbdoc overhaul

[vszakats]

Hi All,

In the last few day I've refactored hbdoc in 3.4 and made

improvements to create more readable output using existing

NFDOCs (with fixes and minor adjustments). As a side-effect,

hbdoc also became smaller and faster. Very basic Markdown

support have also been implemented.

It's been now resynced to 3.2 along with doc updates:

   https://harbour.github.io/doc/

"before" and "after" screenshots attached below. Enjoy.

-Viktor

[Klas Engwall]

Hi Viktor,

Thanks :-)

The screenshots you posted are looking very good. Now, while you are at
it, can you please also fix the spelling of "C level API compatability"
in hbdoc.prg to "C level API compatibility"? Someone with a heavy
American accent must have written that line from how it sounds over
there. It has annoyed me for some time :-)

Regards,
Klas

[José Maria Quintas]

I made a test here.

Nothing, but files on Harbour doc format. (here from a MySQL database)
It is like a "doc viewer".
Content on "See also" is used to link pages.
Generate some main docs using Harbour routines as example, because they do not exists on Harbour.

http://www.harbourdoc.com.br/show.asp?key="Harbour"

And a "doc viewer" like this could be made using Harbour source code.

José M. C. Quintas

--
You received this message because you are subscribed to the Google Groups "Harbour Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to harbour-deve...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Toninho]

Nice job, thank you.

[vszakats]

The screenshots you posted are looking very good. Now, while you are at
it, can you please also fix the spelling of "C level API compatability"
in hbdoc.prg to "C level API compatibility"? Someone with a heavy
American accent must have written that line from how it sounds over
there. It has annoyed me for some time :-) 

Thanks Klas. I'll fix this (and some more) in a next commit.

-Viktor

[vszakats]

Hi José,

On Wednesday, October 26, 2016 at 9:38:56 PM UTC+2, JoséQuintas wrote:

I made a test here.

Nothing, but files on Harbour doc format. (here from a MySQL database)
It is like a "doc viewer".
Content on "See also" is used to link pages.
Generate some main docs using Harbour routines as example, because they do not exists on Harbour.

http://www.harbourdoc.com.br/show.asp?key="Harbour"

And a "doc viewer" like this could be made using Harbour source code.

I'm so far siding with static page generation because of

the simplicity and the advantage that it can be hosted 

practically anywhere (like now on GitHub) with no server

code and machine to maintain and worry about.

(even a static page can be made dynamic by using

JS and reading the doc from a JSON "database".)

-Viktor

[José Maria Quintas]

No, it's not about site.
I want to show that doc files already have all is needed.
hbdoc already create html from docs.
the only thing to do is transform see also to links.
Can be all static pages, each doc a static page, hbdoc can do this.

José M. C. Quintas

[vszakats]

On Thursday, October 27, 2016 at 1:36:43 PM UTC+2, JoséQuintas wrote:

No, it's not about site.
I want to show that doc files already have all is needed.
hbdoc already create html from docs.
the only thing to do is transform see also to links.
Can be all static pages, each doc a static page, hbdoc can do this.

Transforming "see also" items into links got implemented

in these recent changes (can't link across components though,

and they are not validated/verified).

(there was a casing related regression that I just fixed)

I've also added an index page with TOC, split HTML source

per component and added 'edit' buttons.

-Viktor

[José Maria Quintas]

It is ready. Nice job. Thank you.

And there is a Clipper documentation too.

José M. C. Quintas


José M. C. Quintas

Em 27/10/2016 09:54, vszakats escreveu:
>
> Transforming "see also" items into links got implemented
> in these recent changes (can't link across components though,
> and they are not validated/verified).
>
> (there was a casing related regression that I just fixed)
>
> I've also added an index page with TOC, split HTML source
> per component and added 'edit' buttons.
>
> -Viktor
>

> -

[vszakats]

Hi,

Some improvements since the initial post:

- added new index page

- added menu in header to jump between components

- added support for other language than English (currently: pt-BR)

- added language selection menu to header

- added table of content in sidebar

- added hover highlight of long function names in sidebar

- added 'edit this page' links for each doc section

- resolved SEE ALSO links to work across components

- added option for reproducible output

- moved hbdoc to contrib directory (3.4)

- snapshot builds now include HTML documentation (3.4)

- added 'go to index', 'go to top' links for each function

- recognize legacy markups like <b>

- added small vector logo to header

- fixed some HTML5 validation issues

- content doctoring:

  - merged some Pull Requests with new/improved docs (Thanks Pete)

  - convert source file references to links (matching the

    revision of the documentation)

  - autodetect Harbour functions and convert them to links

    if possible, otherwise just highlight them

  - autodetect and highlight keyboard keys and symbols like

    command and constants

  - autoremove PROCEDURE Main()/RETURN enclosures from examples

  - remove indent from in-content code snippets

  - implement proper rendering for multiline SYNTAX sections

  - manually fixed/improved doc markups in several places

  - (lots of heuristics and tricky code)

Links:

https://harbour.github.io/doc/

https://harbour.github.io/doc/pt-br/

-Viktor

[Sami Laham]

Nice Job !!!!

Thank you Viktor.

[Ash]

A job done well. Thank you.

Ash

[vszakats]

Hi,

Further hbdoc improvements:

- link to the source code of functions/components,

  if it could be auto-detected

- add 'Permalink' button for each entry

- localise doc elements not coming from NFDOC sources

- adjust format for printing, so that PDF export from a browser

  results in usable output

- multi-language support is now enabled by default

- add source code highlighting (JavaScript-based) for

  examples and code snippets

- pin page header, to make switching components easier

- scrollable sidebar

- improve file and keyword detection

- fix lots of minor content bugs and added many tags

- readability improvements

- fix tapping on menus on iOS/Safari

Links:

https://harbour.github.io/doc/

https://harbour.github.io/doc/pt-br/

Brazilian Portuguese string translations here:

https://www.transifex.com/harbour/harbour/translate/#pt_BR/hbdoc/100409468?reviewed=no

(reviews/corrections are welcome)

-Viktor

[frank van nuffel]

Hi Viktor,

Thank you very much!  Harbour is since long known to me, as a language/compiler/environment, but I never inclined to start using it because not wanting to put time and effort in putting the pieces together myself, in terms of documentation _and_ (above all) links to the source code

Seems you just done both (and pbly more) .oO on top of hbmk2

This is a great presentation as far as I can tell

Congratulations!

Frank


Op maandag 7 november 2016 16:56:44 UTC+1 schreef vszakats:

[vszakats]

Thank you, Frank!

-Viktor

[vszakats]

Some more news since the previous message:

- Clipper 5.3 and Clipper Tools 3 docs have been added

- this was facilitated by a custom made script that converts

  decompiled .ng files into NFDOC sources. It uses untouched

  original sources plus a few hunks worth of small patch

  fixing an original typo. Plus a hbmk2 -fixcase run.

- improve and extend internal heuristics dealing with the now

  much larger and diverse content

- rework entry IDs for permalinks and interlinks. Now they are

  quite nice and clean.

- rework internal references detection. It now works across

  components and languages, and it will show a menu if the

  reference can be found in multiple places (f.e. both Clipper and

  Harbour docs, or both hbct and CT3 docs)

- migrated out-of-NFDOC copyright headers inside NFDOC

  entries.

- add coverage statistics: per component, per language.

  Currently: ~21% for all English docs. 23.8% for Harbour core.

- doc content improvements

- still a lot of content issues, there are limits to automatic corrections

  and detection. Cl*pper class docs are not in good shape after

  auto-conversion.

- bad news: hbdoc sources are messier than ever

- last but not least: new Harbour core docs, thanks to Pete.

Clipper docs:

  https://harbour.github.io/doc/clc53.html

  https://harbour.github.io/doc/clct3.html

Index:

  https://harbour.github.io/doc/

Please note that the most recent homepage revision resides here:

  https://vszakats.github.io/harbour-core/

-Viktor

[Hazael]

Very nice presentation and professional work.
Well done Viktor!

Qatan

[Alex Strickland]

Hi Viktor

Would you consider adding some issues that are low hanging fruit for the docs, and which other people might be able to take up?

--
Regards
Alex

--
You received this message because you are subscribed to the Google Groups "Harbour Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to harbour-deve...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

-- 

[vszakats]

Hi Alex,

On Friday, November 11, 2016 at 5:20:38 PM UTC+1, Alex Strickland wrote:

Hi Viktor

Would you consider adding some issues that are low hanging fruit for the docs, and which other people might be able to take up?

Good question, thanks for it.

Not sure how low-hanging they are, but these come to mind:

- better Markdown parser would be nice (even as a separate project,

  to be integrated as a second step later).

- lots of cleaning up needed in original Clipper docs:

   - updates to play better with hbdoc parser, add tags

   - fix broken 'see also' links

   - add <table>, <table-noheader>, etc tags

- but before that, advise how to start with that. Is it legal to upload

  decompiled .ng sources to a repo? (decompiled and HTML-ized

  copies are floating on the internet since many years.)

- anything content related in existing Harbour docs:

    - typos, formatting errors, fixing incorrect/outdated information

    - review/replace/extend existing text

    - reviewing STATUS/COMPLIANCE/PLATFORMS fields, they

      are in many places incorrect/incomplete/missing.

    - better and/or more examples

    - document new functions. Probably it's a good idea to document

      hb_*() functions and focusing only on things that work differently

      in Cl*pper compatibility functions, highlighting platform differences,

      possible extra features or other useful Harbour-specific information.

      (redoing existing C5.3 docs from scratch looks unnecessary).

      [Later these extra bits may even me merged on top of Cl*pper docs.]

    - document contribs that are currently totally undocumented  

Here's a list of Harbour functions referenced, but with references

broken because of missing doc entry:

AdsBinaryToFile()

AdsCloseTable()

AdsConnect()

AdsFileToBinary()

AdsGetKeyNum()

AdsIsRecordLocked()

AdsRegisterProgressCallback()

AdsSetFileType()

AdsSetSearchPath()

AdsSetServerType()

AdsShowDeleted()

Checksum()

Crypt()

DispOutAt()

HighByte()

LowByte()

MakeHI()

QQOut()

RangeRepl()

__Accept()

__Eject()

gdImageColorAllocate()

gdImageColorTransparent()

gdImageTransparent()

hb_BChar()

hb_BCode()

hb_SToD()

hb_StrFormat()

-Viktor

[Pritpal Bedi]

Hi Viktor

 

Clipper docs:

  https://harbour.github.io/doc/clc53.html

  https://harbour.github.io/doc/clct3.html

Index:

  https://harbour.github.io/doc/

Please note that the most recent homepage revision resides here:

  https://vszakats.github.io/harbour-core/

Excellent job!

Do you intend to keep above links as is or those are 

scheduled to be changed in future ? I am in the middle of 

adding the feature to various links of Harbour documenttaion 

in HbIDE and HbDBU and thinking of embedding these 

links literally instead of providing interface to add users own.

Thanks.

Pritpal Bedi

a student of software analysis & concepts

 

[vszakats]

Hi Pritpal,

Thank you Pritpal, I'm glad you find this useful.

Things are not completely settled yet (in particular the direct 

Clipper doc URLs) and of course may also change in the long run,

but at the moment I don't have plans to update the doc links.

If there will be any change I'll be making sure to post a note about

it on this list.

To minimise exposure to a change, you may consider using this

root URL: https://harbour.github.io/doc/

-Viktor

[vszakats]

Updates on the doc overhaul:

- rework the way source code of functions is being discovered.

  It means that the 'source code' button now works - and accurately 

  so - for _every_ function. It now even jumps to the precise line

  number. The requirement to use the same filename for NFDOC .txt

  and source code is no more.

- detect redirected functions (synonyms) and link to their effective

  source code, instead of the redirector stub.

- fix some broken 'see also' links by better doing a better job at

  identifying those.

- show source filename when hovering over the 'source code' button

- link to the Harbour source code implementation from Cl*pper docs.

- much improved keyword detection inside doc sources.

  This mainly affects legacy docs, like Cl*pper, CT3

- add 'Search' button to lookup a function references inside the source

  repository and also in these very forums.

- rewrite the Norton Guide parser to parse the .ng files directly and

  not require and MS-DOS based decompiler anymore. Output is .json.

  Thanks to Dave Pearson's eg project sources for .ng file parsing details:

      https://github.com/davep/eg

- rewrite .ngs parser to a .json parser, fixing/improving some content

  related issues along the way

URL:

  https://harbour.github.io/doc/

To contribute, press the "Improve this doc" button.

-Viktor

[Gerald Drouillard]

Very nice.  Thank you.

--
You received this message because you are subscribed to the Google Groups "Harbour Developers" group.

To unsubscribe from this group and stop receiving emails from it, send an email to harbour-devel+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

Regards
--------------------------------------
Gerald Drouillard
Cell: 734.502.4356

[vszakats]

To forum admins:

It may be nice to update the "Clipper 5.3 docs" links in the 

header of this and user's forums to:

   https://harbour.github.io/doc/

It currently points to http://x-hacker.org/ng/53guide/, which

doesn't work since a while.

Thank you.

-Viktor

[Bacco]

Hi, Viktor

I've changed the link on Harbour Developers list welcome message.

Regards

Bacco

[Bacco]

PS: not an Admin at all, but mods have edit privileges in the welcome message)

Need others to change the users and commits list, I have no access there.

Regards

[vszakats]

Thank you Bacco, also for the cleanups, it's looking great.

The user's list header could use such cleanups as well,

f.e. the harbour.github.io homepage is likely more than

temporary, so the old one can just be replaced by it.

-Viktor

[Nenad Batoćanin]

Great job, thank you very much!

Regards, NB