From 148ad8f5ed83ed7e616b60a20bad7f2b1d73c247 Mon Sep 17 00:00:00 2001
From: Jukka Aho <ahojukka5@gmail.com>
Date: Sat, 9 May 2026 17:19:45 +0300
Subject: [PATCH] docs(io): describe default Gmsh reader and Legacy ingest

Rewrite the module README now that Abaqus/Code_Aster stacks live behind the
opt-in Legacy flag and only Gmsh ASCII ingest ships unconditionally.

- Document `JULIAFEM_ENABLE_LEGACY=1` and `src/legacy/io/` for vendor parsers.
- Focus the file list on `gmsh_reader.jl` / `GmshReader` instead of deleted stubs.
- Trim emoji/status tables and stale usage snippets; note roadmap for a native
  `.inp` path aligned with `Mesh{T}` / `create_elements!`.
---
 src/io/README.md | 132 +++++++----------------------------------------
 1 file changed, 18 insertions(+), 114 deletions(-)

diff --git a/src/io/README.md b/src/io/README.md
index 162f108..8d2d799 100644
--- a/src/io/README.md
+++ b/src/io/README.md
@@ -1,120 +1,24 @@
-# I/O Module - Mesh Import/Export
+# src/io/
 
-**Purpose:** Read and write mesh files from various FEM software packages.
+Mesh readers that ship with the current 0.x package surface.
 
-## Supported Formats
+The Abaqus `.inp` and Code Aster `.med` readers were built around the
+older `Element(Poi1, ...)` constructors and the Dict-based field
+system; they have been moved into the optional `JuliaFEM.Legacy`
+submodule (see `src/legacy/io/`). Set the environment variable
+`JULIAFEM_ENABLE_LEGACY=1` before `using JuliaFEM` to load them.
 
-### Abaqus (.inp)
-**Status:** ✅ Active  
-**Files:**
-- `AbaqusReader.jl` - Main reader with keyword parsing
-- `abaqus_reader.jl` - Simplified reader
-- `abaqus_download.jl` - Download example meshes
-- `keyword_register.jl` - Keyword parsing system
+## Files
 
-**Use:** `mesh = read_abaqus("model.inp")`
+- `gmsh_reader.jl`
+  Self-contained Gmsh `.msh` (ASCII format 4.1) reader.
+  Defines its own `JuliaFEM.GmshReader` submodule with `GmshMesh`,
+  `read_gmsh_mesh`. Has no dependency on legacy types and is loaded
+  unconditionally.
 
-### Code Aster (.med, .rmed)
-**Status:** ⚠️ Requires HDF5 (weak dependency)  
-**Files:**
-- `AsterReader.jl` - Main Aster reader
-- `aster_reader.jl` - Simplified reader
-- `read_aster_mesh.jl` - HDF5-based mesh reading (NOT included - needs HDF5.jl)
-- `read_aster_results.jl` - HDF5-based results reading (NOT included)
+## Future work
 
-**Strategy:** Implement as weak dependency - only load if HDF5.jl available
-
-### Gmsh (.msh)
-**Status:** ✅ Active  
-**Files:**
-- `gmsh_reader.jl` - Gmsh mesh file parser
-
-**Use:** `mesh = read_gmsh("mesh.msh")`
-
-## File Organization
-
-### Core Readers
-- `io.jl` - Common I/O utilities
-- `gmsh_reader.jl` - Gmsh format
-- `abaqus_reader.jl` - Simple Abaqus reader
-- `aster_reader.jl` - Simple Aster reader (no HDF5)
-
-### Legacy Vendor Package Infrastructure
-- `AbaqusReader.jl` - Full Abaqus reader (from vendor package)
-- `AsterReader.jl` - Full Aster reader (from vendor package)
-- `keyword_register.jl` - Keyword parsing system
-- `parse_mesh.jl` - Generic mesh parsing
-- `parse_model.jl` - Model structure parsing
-- `create_surface_elements.jl` - Surface element extraction
-
-### Disabled (Require HDF5)
-- `read_aster_mesh.jl` - ❌ Commented out (needs HDF5.jl)
-- `read_aster_results.jl` - ❌ Commented out (needs HDF5.jl)
-
-## Design Philosophy
-
-### Weak Dependencies
-For optional formats requiring heavy dependencies (HDF5):
-```julia
-# In Project.toml
-[extras]
-HDF5 = "..."
-
-# In src/io/
-if isdefined(Main, :HDF5)
-    include("read_aster_mesh.jl")
-end
-```
-
-### Two-Tier Strategy
-1. **Simple readers** - Basic functionality, minimal dependencies
-2. **Full readers** - Complete keyword support, complex features
-
-Users can choose based on needs.
-
-## Future Work
-
-### Export Formats
-- VTK/VTU for visualization
-- Exodus II for multi-physics
-- JSON for web applications
-
-### Import Enhancements
-- NASTRAN (.bdf, .nas)
-- ANSYS (.cdb)
-- CalculiX (.inp)
-
-### Consolidation
-- Unify simple vs full reader approaches
-- Document which reader to use when
-- Benchmarks for large meshes
-
-## Usage Examples
-
-```julia
-using JuliaFEM
-
-# Abaqus
-mesh = read_abaqus("cantilever.inp")
-
-# Gmsh (if gmsh_jll available)
-mesh = read_gmsh("geometry.msh")
-
-# Aster (if HDF5 available)
-mesh = read_aster("model.med")
-```
-
-## Dependencies
-
-**Required:**
-- None (pure Julia)
-
-**Optional:**
-- `gmsh_jll` - For Gmsh API access
-- `HDF5.jl` - For Code Aster .med files
-- `Downloads.jl` - For downloading example meshes
-
----
-
-**Maintainer:** JuliaFEM Team  
-**Last Updated:** November 21, 2025
+A current-API replacement for the Abaqus reader (returning
+`Mesh{T<:AbstractTopology, N}` and elements built via `create_elements!`)
+is on the roadmap. When it lands it will live here next to
+`gmsh_reader.jl`.