SDFGET(1)

📦
version 2.001+1 · 3 versions
, in debian trixie, ubuntu noble, ubuntu questing

✨ SDFGET(1) ✨

okay bestie, sit down, hydrate, and let me tell you about sdfget — it lives in section 1 of the user-contributed Perl documentation, and it is literally the girl who goes digging through your source code to pull out the documentation you buried in there. 🦋

🌸 NAME 🌸

sdfget — the Documentation Extraction Utility. That's it, that's her whole job title, and she ate. 💅

🎀 PURPOSE 🎀

sdfget extracts documentation embedded in source code. Not me explaining it twice, that's genuinely the purpose section. She finds the docs hiding in the comments and yanks them out. Periodt. 👑

⭐ USAGE ⭐

Here's the whole vibe, verbatim, because commands are sacred and we do not paraphrase commands in this house:

 usage  : sdfget [-h[help]] [-o[out_ext]]
         [-l[log_ext]] [-O[out_dir]]
         [-f formatting_filename] [-g[get_rule]]
         [-r[rpt_file]] [-s scope] [-i]
         [-v[verbose]] file ...
purpose: extract documentation embedded in source code
version: 2.000    (SDF 2.001)

And here are all the options, one per bullet, no skips, no shortcuts, because we respect a full list in this group chat:

  • -h — display help on options
  • -o — output file extension
  • -l — log file extension
  • -O — output to input file's (or explicit) directory
  • -f — filename to use when formatting the output
  • -g — rule to use to get documentation
  • -r — report file
  • -s — scope of documentation to be extracted
  • -i — only output lines not extracted
  • -v — verbose mode

💖 DESCRIPTION 💖

The -h option is your help bestie. Give it nothing and it hits you with a brief description of every single option. Give it an option letter as a parameter and it spills the attributes for that option specifically. iykyk. 🔥

By default, generated output goes to standard output. If you want output to go into a file per input file, use the -o option to name an extension for the output files. And if you say -o with no parameter at all? It just assumes an extension of out. Casual. Slay.

Same deal with errors: error messages go to standard error by default. Use -l to make a log file per input file. And if -l shows up with no parameter, an extension of log is assumed. 🍓

By default, generated output and log files get created in the current directory. Use -O to specify an explicit output directory. And if -O is specified without a parameter, the input file's directory is what gets used. Easy.

The -f option lets you specify a filename to use when formatting the output. This is so useful when the text is coming from the standard input stream. 🫶

🧚 The get-rule, explained 🧚

The get-rule nominates the formatting of the embedded documentation that's getting extracted. Every currently defined get-rule assumes the documentation lives in comment blocks, in one of these three formats:

>>section_title1::
text of section 1, line 1
text of section 1, line ..

>>section_title2::
text of section 2, line 1
text of section 2, line ..
>>END::

>>section_title3:: text of section 3

The first form is the one everybody uses, it's the main character. In that format, the text in a section extends until the end of the current "comment block" or the start of the next section — whichever comes first. The second form (yes, the one that explicitly says where the section ends) is your girl when you want to sneak in some normal comments (i.e. non-documentation) that you do not want extracted. And if the text is short? Third form, go off. 🌈

Regardless of which format you use, if a section is found that's already defined, the text of the section is concatenated onto the existing text. That's the whole point — it lets the documentation for each entity sit immediately above where it's defined in the source code. Chef's kiss. 👑

💅 The -g option and its get-rules 💅

The -g option specifies the get-rule to use. The available get-rules differ on the prefix they expect at the front of each line, like so:

 Rule                              Prefix
 perl                              #
 cpp                               //
 c                                 * or /*
 fortran                           c (with 5 preceding spaces)
 eiffel                            --
 bat                               rem

Within C code, a trailing space is required after the characters above. For other languages, a trailing space is optional. Within FORTRAN code, the c character must be preceded by exactly 5 spaces. For other languages, zero or more whitespace characters are permitted before the characters above.

So for example, embedded documentation within C code looks like this:

 /* >>Purpose::
  * This library provides a high level interface
  * to commonly used network services.
  */

If -g isn't specified, perl is the default get-rule. And if -g is specified without a parameter, the extension in lowercase of the filename (or the formatting filename, if the text is coming from standard input) is used to guess the get-rule, like this:

 Rule                              Extensions
 cpp                               cpp, c++, cc, hpp, hpp, h, java, idl
 c                                 c
 fortran                           fortran, for, f77, f
 eiffel                            eiffel, ada
 bat                               bat, cmd

🎀 The -r report option 🎀

You can specify a report filename with the -r option. If the name doesn't include an extension, sdg is assumed. Reports give you a mechanism for:

  • selectively extracting sections, and
  • rudimentary reformatting (e.g. to SDF)

If no report is specified, all sections get output in this format:

 section_title1
 section_text1

 section_title2
 section_text2

If -r is specified on its own, default.sdg is assumed. That report selects the set of sections (within the SDF documentation standards) which form the user documentation, and formats them into SDF. Details on the report format are specified below. Reports are searched for in the current directory first, then in the stdlib directory within SDF's library directory. 🔍

🌸 -s, -i and -v 🌸

The -s option can be used to specify the scope of the documentation to be extracted.

Heads up bestie: this is an experimental feature and may change, so most users should avoid using it. 🚨

The -i option outputs only those lines which the get-rule did not match. This is genuinely useful for extracting non-documentation from a file so you're left with just the code.

Note: The -r option is ignored if -i is specified. 💀

The -v option enables verbose mode. This is great for seeing which rule is being used for each file. Peak transparency, we love her. ✨

🔥 EXAMPLES 🔥

To extract the user documentation from a SDF application written in C++ (xyz, say) and save it into xyz.sdf:

       sdfget -gcpp -r -osdf xyz.cpp

Ate. No crumbs. 💖

😭 LIMITATIONS AND FUTURE DIRECTIONS 😭

It would be nicer if the get-rule was always guessed from the filename extension, ngl — but changing the default away from perl could break existing scripts. So get-rule guessing has to be explicitly enabled by specifying the -g option without a parameter. It's giving "we can't have nice things because backwards compatibility said no". 🙈

and that's the whole page, bestie 🫶 this was the SDFGET(1) manual, brought to you by perl v5.36.0, dated 2023-08-02. go forth and extract responsibly. 💜

📦 where this page comes from