Opened 2 months ago

Last modified 8 weeks ago

#33741 new enhancement

Format code blocks inside markdown files (documentation)

Reported by: bduszel Owned by:
Priority: Very Low Milestone: Tor: 0.4.4.x-final
Component: Core Tor/Tor Version:
Severity: Minor Keywords: doc easy
Cc: Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

There are issues with code blocks inside some *.md files (some files use code blocks syntax, some do not). First of all, it's not consistent but what's really bad is when *.md file is being displayed incorrectly. You can find an example of what I'm saying in CodingStandards.md under How we log changes section.
https://github.com/torproject/tor/blob/master/doc/HACKING/CodingStandards.md#how-we-log-changes

Part of the git log output is still displayed as a regular text rather than a formatted code block.

Goal of this ticket is to go through all *.md files under doc and doc/HACKING directories and format code snippets accordingly.

```c
// code snippet
// written in
// C language
```
```bash
// command to be run
// inside bash
```

This should fix the issues described above and enable syntax highlighting on supported websites and editors.

Child Tickets

Change History (3)

comment:1 Changed 2 months ago by nickm

I wonder if there's some way to automate this change, at least heuristically.

comment:2 Changed 2 months ago by bduszel

We could start by looking for code blocks without language specified.

```
// bash code
```

vs.

```bash
// bash code
```

Another check could be to search for all the lines starting with $ and making sure these are inside bash code blocks. This approach won't work for code blocks with command output though:

$ git describe --contains ebab521525 // only this line would be recognized
tor-0.3.2.3-alpha~15^2~4

However such search would at least let us know where commands are being used and what we should check manually.

No idea how to recognize the following scenario though:

If you're writing an assertion to test for a bug that you _can_ recover from,
use `tor_assert_nonfatal()` in place of `tor_assert()`.  If you'd like to
write a conditional that incorporates a nonfatal assertion, use the `BUG()`
macro, as in:

        if (BUG(ptr == NULL))
                return -1;

## Allocator conventions

comment:3 Changed 8 weeks ago by dgoulet

Milestone: Tor: 0.4.4.x-final
Note: See TracTickets for help on using tickets.