(VHDL) Extract line comments marked by '--' to create a Markdown document


#1

Hi,

I’m writing VHDL code.
Comment line are line with – in front.
Classic VHDL language doe not have such a thing as block commands.
The newest version VHDL-2008 has block commands, but it’s not widely spread/used.
I want to write comments in the code to be in markdown so that publishing is easier.
Now the question:
Is it possible to let markdown ignore the – in text lines?
Any package that can do this?

Thanks,


#2

Hello.

Could you explain again please.

Which option are you talking of?..

  1. Extract from the code the comment lines marked with - which will built a Markdown document.

  2. Publish the code as a Markdown document where - comment lines are the text body of the document and the rest is code quotes.

  3. When copy-paste code lines into a Mardown document, the - comment lines are excluded from the pasted text.

  4. Not any of the above. (Please specify)


Bonus question - how is the `-` comment indicator used?
  1. Only at start of the line

  2. At end of code line

  3. Inside the code line

  4. All of the above.

Regards.
- Dan


#3

VHDL source code has commenting lines indicated with – (twice "2D"hex, minus sign).
What I would like to do is publish the comments as markdown text.

The “–” only at the start of a line.

Goal is to have in-code description block (entered as comments) of a certain function or functionality and have the possibility to extract the descriptions, publishing them as markdown. This would ease writing documentation al lot.

Thanks,

Marc


#4

Hi Marc.

Could you publish a few lines of code for me please.
(no need for a full project… fictional code is okay)

How would you want the text that is extracted be formatted. Or is it already in the markdown format.

I think I know what you ask. You could have a small piece of code in your init.coffee file that extracts the information from the open document using Atom’s API (atom.io/docs/api). Specifically https://atom.io/docs/api/v1.21.1/TextEditor#instance-scan.

Without script you can use Atom’s find function ->

  1. regular expression to find: ^[-]
  2. find all
  3. press Alt + Enter which places cursors everywhere
  4. move cursor to make a selection (example: Shift + End ).
  5. copy and then paste in a new document.

Maybe try the find method first…
- Dan


#5

Hi Dan,

Thanks for your fast reply.
Attached a code extract.
It’s little bit of code and lot of comment but I think that you can see
what I mean with this.

I’ll try you suggestions.

Kind regards,
s,
Marc

Marc Defossez

P**Please do not print this e-mail unless you really need to.

This email and any attachments are intended for the sole use of the
named recipient(s) and contain(s) confidential information that may be
proprietary, privileged or copyrighted under applicable law. If you are
not the intended recipient, do not read, copy, or forward this email
message or any attachments. Delete this email message and any
attachments immediately.


#7

Unluckily the VHDL code syntax is not recognised within this forum.
The language-vhdl package does render the code correctly within Atom.

Sample code..
IntBase_Dly_Clk        <= IntRx_SysClk;
---------------------------------------------------------------------------------------------
-- Use of PHY_RDEN.
-- Use of PHY_RDEN is TIME and MIG and thus these signals must be tied HIGH all the time
IntBase_Tx_Phy_Rden <= LowVec(3 downto 0);
IntBase_Rx_Phy_Rden <= HighVec(3 downto 0);
---------------------------------------------------------------------------------------------
-- # Clock Reset - RIU State machine
-- In the non-wizard design the clocking and RIU stuff happens from within the Clock_Reset
-- hierarchical block. But in the the wizard design the Clock_Reset hierarchical block is
-- not needed since PLL and reset sequencers are included in the cores.
-- What is not included in the cores is the RIU accessing state machine, so that has been
-- extracted from the Clock_Reset block and is used here in with the wizard design.
-- The *Clock_Reset.vhd* source can be found in the /Libraries/clkrst_lib folder.
-- The *Riu_StateMach.vhd* can also be found in that folder.
--
-- The clocks of the *Riu_StateMach* hierarchical block are no longer outputs but inputs.
-- Why? Well:
-- All PLL and reset stuff is assembled into the IO IP cores generated by the HSSIO-Wiz.
-- Since clocks are no longer generated together with the state machine, the clocks
-- for the state machine need to come from outside the file, from the IP cores.
--
-- ## Pin and attribute description
--  - C_InSimulation  : Attribute to force the RIU state machine in a simulation mode.
--                    : the state machine is partially overrules and only provides Fixed
--                    : values form the read registers.
--  - ClockIn         : RIU clock input, must be supplied by the HSSIO core
--  - ResetIn         : Reset input from external, goes also the the HSSIO cores
--  - Tx_Dly_Rdy      : TX: Input from the HSSO core (BITSLICE_CONTROL output).
--  - Tx_Vtc_Rdy      : TX: Input from the HSSO core (BITSLICE_CONTROL output).
--  - Tx_Bsc_EnVtc    : TX: Output to the HSSIO core (input for the BISTLICE_CONTROL).
--  - Tx_Bs_EnVtc     : TX: Output to the bitslices (Input for the BITSLICEs).
--  - Rx_Dly_Rdy      : RX: Input from the HSSO core (BITSLICE_CONTROL output).
--  - Rx_Vtc_Rdy      : RX: Input from the HSSO core (BITSLICE_CONTROL output).
--  - Rx_Bsc_EnVtc    : RX: Output to the HSSIO core (input for the BISTLICE_CONTROL).
--  - Rx_Bs_EnVtc     : RX: Output to the bitslices (Input for the BITSLICEs).
--  - Tx_WrClk        : input, Application clock generated by the TX HSSIO core PLL
--  - Rx_SysClk       : input, Application clock generated by the RX HSSIO core PLL
--  - Tx_Locked       : Input, signal generated by the HSSIO core.
--  - Rx_Locked       : Input, signal generated by the HSSIO core.
--  - Tx_LogicRst     : output, Reset for application logic generated by the state machine.
--  - Rx_LogicRst     : output, Reset for application logic generated by the state machine.
--  - Riu_*           : RIU access ports.
--                    : There is one RIU per nibble, thus two RIU per byte.
--  - Riu_Prsnt       : Input, normally indicates if a RIU interface is present.
--                    : Not used in the HSSIO cores. RIU presence is there set
--                    : by a tick-box in the wizard.
--                    : The signals are tied high or low in an upper level.
--============================================================================================
Byte_TopWizard_RxTx_I_Riu_StateMach : entity clkrst_lib.Riu_StateMach
    generic map (
        C_InSimulation      => C_InSimulation
    )
    port map (

…with formatting
https://pastebin.com/ZATiGBZG

The request is to extract the documented lines to make a Markdown document.
My proposal is to make a script in init.coffee to do this task.

@defossez - Marc, I will see if I can make some sample idea… just no concrete promises.
A usage note - you can click the pencil to make changes to any of your own posts.
Screenshot-2017-10-19 Atom Discussion

- Dan


#8

If I understand the question correctly, you could use Markdown Preview Enhanced to render Markdown, add vhdl files to the list of extensions to be treated as Markdown and use the custom Markdown parser facility to strip the lines that start with a dash before rendering. Something like (not tested)

module.exports = {
  onWillParseMarkdown: function(markdown) {
    return new Promise((resolve, reject)=> {
      markdown = markdown.match(/^--.*$/gm).join('\n').replace(/^--(.*)/gm, ($0,$1) => $1)
      return resolve(markdown)
    })
  },
  onDidParseMarkdown: function(html) {
    return new Promise((resolve, reject)=> {
      return resolve(html)
    })
  }
}

might do.

Edit: now I’m thinking you might have meant that you want to keep only the lines that start with a dash, strip the dash, and render the rest as Markdown. The same strategy applies, with a different regexp.

Edit 2: the updated regexp should work.


#9

@dpo: … that is an interesting proposal that needs more study.
Thank you!


#10

Please find below a proposal that can be listed in init.coffee.
It is just enough to get the conversation going, as it is not perfect.
Some more study of @dpo is also a good idea.

Extract comments marked by ‘–’ to a new Markdown file

# init.coffee

# Global applied object variable
# Used by onDidOpen task to dispose of listener after being Used
# ? -> Is better method available to dispose of the listener?
root = exports ? this

# This command needs to be bound to a shortcut
# Alternatively called by command pallet (Ctrl+Shift+P)
atom.commands.add 'atom-text-editor', 'custom:comments-to-markdown', ->
  return false unless editor1 = atom.workspace.getActiveTextEditor()
  buffer1 = editor1.buffer  # copy of source
  buffer2 = ''  # initialize buffer for extracted text
  
  search = /^[-]{2}[ ](.*)$/g  # pattern identified as a comment
  
  editor1.scan search,  (grab) ->
    # newline characters are not used correctly in Markdown
    # optional: force new line type characters
    buffer2 = buffer2 + grab.match[1] + '<br>\n'
    
  # spaces ' ' is not rendered correctly in Markdown ->
  # optional: replace by HTML characters
  buffer2 = buffer2.replace(/[ ]{2}/g,'&nbsp;&nbsp;')
  # console.log buffer2  # for testing

  # temporary file.. a absolute path would be best
  atom.workspace.open('./file.md')
  
  # Creating a listener: task to be executed when file is open
  # important! handled with disposable -> global variable
  # important! close listener by dispose() function
  # TODO:
  # 1. check correct file is opened by using 'callback.uri'
  # 2. get trigger for markdown-preview to work correctly
  root.disp = atom.workspace.onDidOpen ->
    editor2 = atom.workspace.getActiveTextEditor()
    editor2.setText(buffer2)
    atom.commands.dispatch(editor2, 'markdown-preview:toggle')
    root.disp.dispose()  # close listener

#11

Dan,

Thanks for the code, I will try it out the next days (working on a VHDL design right now) and report back.
It’s for me also a good start in coding for Atom.
I’m using Atom for a while now but never did any coding to adapt it to my needs or had time to write a package. This is a good reason to step into the “hackable editor”.

Dpo, Your idea looks nice but will not have much success in hardware circles. It’s as you write in the last lines, what’s wanted is to extract from the VHDL source the lines marked (bgin of the line) as comment ‘minus minus’ lines and join them into a new Markdown document. forgive me my ignorance (I’m an hardware engineer) but what exactly is a ‘regexp’? (possibly the answer is RTFM, just let me know).

Thanks again,

Marc


#12

Thank you for your reply, your feedback would be equally welcome.

The reason I still use Atom is the ‘hacking ability’. I program PLCs - which is not so possible to do in Atom. But the all the text preparations around the project is simplified by using Atom and the custom hacks. Have a look at the documentation section of Atom: [atom.io/docs].



regexp is called a few other names… full name is regular expressions. It is a language on its own, used for identifying patterns for find / find-replace kind of applications. Regular expressions is so powerful that it has been absorbed into programming languages, though implementation into Python and Javascript (examples) look different.

Regular expressions is a subject worth learning. It is a little hidden but it is (almost) everywhere. Before Atom, for me it was instrumental in processing text in Notepad++ with find-and-replace. In Atom we have this when selecting the .* button in the find functionality.



The base concept proposed by @dpo will work. What is not said is that the package he speaks of makes it possible to have a import instruction in your Markdown. The import instruction then points to your VHDL file.

You need to configure the package on how the VHDL would be formatted when using the import instruction. It is this bit that @dpo spoke about. Very do-able and in the long run a good idea! The problem is that the raw Markdown text will only work correctly inside the package AFAIK as the Markdown standard is extended. I do not know if regular Markdown text can be generated / exported. A PDF representation could however be an option as an export.



+ wow… that was a mouthful.
+ I do hope that the above is of value to you and others.

Cheers.
- Dan

NOTE: Above notes are given as an opinion from a novice.


#13

Dpo, Your idea looks nice but will not have much success in hardware circles.

Sorry to hear that :wink:

The solution I proposed allows you to preview the comments parsed as Markdown, but doesn’t extract the Markdown to a new buffer (although Markdown Preview Enhanced will allow you to export the preview as Markdown).

If you’d like to just extract the comments into a new buffer, this appears to work for me:

atom.commands.add 'atom-text-editor', 'custom:extract-doc', ->
  return unless editor = atom.workspace.getActiveTextEditor()
  markdown = editor.getText().match(/^--.*$/gm).join('\n').replace(/^--(.*)/gm, ($0,$1) => $1)
  atom.workspace.open().then (new_editor) ->
    new_editor.insertText(markdown)

and is quite a bit shorter than @danPadric’s solution.

ps: regexp = regular expression


#14

Regex = regexp : understood what it is.
First test with the code.

  • copied the code into my init.coffee

  • close and restart Atom.

  • Empty Atom, no file loaded, empty window called “untitled”.

  • Do “ctrl-shft-P” and type

  • This shows the command: “Custom: Command To Markdown”

  • Click the command generates a second empty window.

  • Load a VHDL file in Atom, In fact open a project and click on a VHDL file.

  • Do “ctrl-shft-P” and type

  • Nothing, there in no command “Custom:…”

  • Close the file, start a new empty text editor window. The projec tis still open.

  • Do “ctrl-shft-P” and type

  • Nothing, there in no command “Custom:…”

  • Close Atom and launch it again with an empty text window.

  • Do “ctrl-shft-P” and type

  • This shows the command: “Custom: Command To Markdown”

  • Click the command generates a second empty window.

Thus as soon as a text file (opened different file .vhd, .txt, …) there i no longer a “Custom: …” command.

What’s wrong?


#15

Didn’t know that Markdown Preview Enhanced could write out a markdown file.
Thought it was just a previewer for markdown text.
Then It might have some chance.
If one could only view markdown in a previewer, that would not be a great succes.

I’ll give it also a try.

Marc


#16

@defossez

Hello Marc.

This is a strange occurrence. I have just now copied the text from this forum and put it in a “clean” Atom (V1.22 Beta). It had an empty init.coffee. The OS is Windows7 … though that should not matter. BUT - - which Atom version number do you have?

The result is as:

This all is academical as the code presented by @dpo is superior. However I would suggest to look at the /-- / (minus-minus-space). The whitespaces - more than one space - and newline present a problem for the Markdown file. I have tried to compensate for this fact in my version.

:disappointed_relieved: it just too bad my version is not helping you - sorry.

- Dan




@dpo

A very nice an compact example you have there. I am analysing this now, but frankly is having difficulty with the ($0,$1) => $1 and .then.

A nice link you provided for RE… very nice.

Thank you for your contribution.
I hope to learn more from you.

Cheers.


#17

Dpo,

Observations:

Installed Markdown-Preview-Enhanced ( I had Markdown-Preview-Plus installed first).
Dropped the first part of code you provided into the parser.js file.
Added .vhd to the extension list of Markdown-Preview_Enhanced.

Vhdl files are now seen as markdown, but the – characters are not stripped off.
Something in the "module.exports … " code I think (will take a look and test over the week-end).

Installed the last bit of code you provided in the init.coffee file.
When running the ctrl-shft-P “custom: Extract-doc” command a copy of the original document is created but without the – characters.


#18

Dan,

Atom version 1.21.1 x64 running on Windoze7 and Ubuntu 16.04
I’ve some commands in my init.coffee file to add items to the right click menu of the editor.
I will remove those and try again.

I’m learning a lot from both of you, thanks.

Kind regards,

Marc


#19

Marc,

I am evaluating that code now and making some few minor mods.

What do you mean with:

Do you want the -- to show? You want to have only the text parts that comes after -- - right?

On another matter…
At some part in the text sample you have:

--  - C_InSimulation  : Attribute to force the RIU state machine in a simulation mode.
--                    : the state machine is partially overrules and only provides Fixed
--                    : values form the read registers.

I would recommend you have it as

-- | NAME | DESCRIPTION
-- |-----: | --------
-- | C_InSimulation  | Attribute to force the RIU state machine in a simulation mode.
-- |                 | the state machine is partially overrules and only provides Fixed
-- |                 | values form the read registers.

In Github flavour Markdown will become:

NAME OF NODE DESCRIPTION
C_InSimulation Attribute to force the RIU state machine in a simulation mode.
the state machine is partially overrules and only provides Fixed
values form the read registers.

However this conversion from your current style using : characters to the above proposal is possible in program… if required.


Minor variation of @dpo’s code->

atom.commands.add 'atom-text-editor', 'custom:extract-doc', ->
  return unless editor = atom.workspace.getActiveTextEditor()
  markdown = editor.getText().match(/^--.*$/gm).join('\n').replace(/^-- {0,1}(.*)/gm, '$1')
  atom.workspace.open('new.md').then (new_editor) ->
    new_editor.insertText(markdown)
    atom.commands.dispatch(atom.views.getView(new_editor), 'markdown-preview:toggle')

#20

A very nice an compact example you have there. I am analysing this now, but frankly is having difficulty with the ($0,$1) => $1 and .then.

What difficulty? It works for me (Atom 1.21.1). Note that in the example file, there are lines of dashes. Those end up in the “Markdown” buffer, except with two dashes stripped out. Those should probably receive special treatment.

Regarding your changes below, I purposefully didn’t give a name to the new buffer to avoid any clash. Every time you extract documentation, you’ll create a file named new.md, risking to overwrite old ones.


#21

Hm. That’s not what happens in my case. Note that when you modify your init script, you have to reload the window (Window: Reload in the command palette) for the changes to become active.